Faye

Pour comprendre ce que nous allons faire, il faut prendre le temps de regarder comment fonctionne faye. Mais avant, nous devons choisir la solution à adopter pour écrire notre librairie. En effet, nous avons deux choix possibles : soit nous pouvons parler directement au serveur faye, soit nous pouvons simuler le comportement d’un client. En fonction de ce choix, nous regarderons telle ou telle partie du code de faye. Bon et puisque c’est moi qui choisis², j’opte pour la seconde solution.

Avant de décortiquer le code, rappelons le cheminement par l’utilisateur lors de l’utilisation de soapbox. Avant tout nous démarrons l’application³. Nous donnons notre username. Ensuite nous indiquons qui nous voulons suivre. Enfin nous racontons notre vie. Ces deux dernières étapes pouvant se faire dans n’importe quel ordre, et autant de fois que nous voulons.

Regardons maintenant le code. Lors de l’accès à l’application (route /) nous recevons la page mise en place par la vue views/index.rhtml. Dans cette vue, ce qui nous intéresse ce sont les lignes suivantes :

40
41
42
43
44
45

  <script type="text/javascript">
    Comet = new Faye.Client('/comet');
    Comet.connect();
 
    Soapbox.init(Comet);
  </script>

Nous créons un client Comet (ligne 41) pour le bus accessible via la route /comet puis nous établissons la connexion (ligne 42). Ensuite nous initialisons l’application (ligne 44). Si nous regardons à quoi correspondent la création et la connexion du client Comet, il faut se plonger dans le code du script comet.js. Ce fichier est généré lors de la création du gem faye à partir de l’ensemble des fichiers contenus dans le répertoire client des sources. Le fichier qui nous intéresse principalement ici est client/client.js. Dans ce fichier vous trouverez le code correspondant à la connexion entre les lignes 75 et 113.

Si nous regardons maintenant le fichier soapbox.js nous pouvons étudier ce qui se passe lors de l’initialisation de l’application. Nous voyons dans ce code que soapbox attend que l’utilisateur saisisse son username. Une fois ceci fait, l’application souscrit au channel /mentioning/<username>, elle masque la zone de saisie du username et affiche les zones de saisie des personnes à suivre et des messages. Elle met ensuite en place les actions correspondantes pour ces deux zones de saisie. La première de ces actions se traduit par la souscription au channel /from/<follow> avec comme callback : accept. La seconde revoie vers la méthode post dont le rôle principal est de publier le message sur le channel /from/<username>.

Outch !

Ce qui est important ici c’est de voir ce dont nous avons besoin pour faire cela. Nous en retiendrons donc la nécessité de développer une méthode de connexion, une méthode de souscription et une méthode de publication. Pour comprendre comment ces méthodes agissent, il suffit de regarder ce qui est fait dans les méthodes correspondantes de Faye.Client.

Je ne vais pas pouvoir, au risque de perdre plus de monde que ceux qui ont déjà lâché prise avant la fin du dernier paragraphe, entrer plus dans les détails. Il va donc falloir me croire sur parole ;) En fait, ce que nous allons faire c’est mettre en place une version cliente du protocole des échanges Comet appelé protocole Bayeux. Je vous engage donc à en lire la documentation si vous souhaitez approfondir le sujet.

Messages

Les échanges entre le client Comet et le bus peuvent se faire de deux façons, soit en long-polling soit en callback-polling. Dans notre cas, nous utilisons la première solution en faisant un envoie en POST du paramètre message, ce dernier ayant pour valeur une chaine JSON.

Mettons cela en place :

module Faye
  class Client
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
 
      # ...
 
    end
 
    # ...
 
    private
    def send( message )
      res = Net::HTTP.post_form( @uri, { "message" => message.to_json } )
      return JSON.parse( res.body )
    end
  end
end

Je place cette méthode en private car elle n’a d’intérêt que pour les méthodes que nous allons écrire ensuite.

Comme vous pouvez le voir, le retour est également une structure JSON.

« Handshake »

Si vous regardez précisément ce qui se passe lors de l’initialisation de la connexion du client Comet, vous verrez qu’en fait, il n’y a pas de connexion véritable, mais un handshake. Cela consiste en fait à se présenter au bus Comet et à obtenir de sa part, un identifiant. Nous devrons, par la suite toujours, utiliser cet identifiant pour communiquer avec le bus.

Le message du handshake doit contenir au moins les champs suivants :

• channel : le channel.
• version : la version du protocole.
• supportedConnectionTypes : les types de connexions supportées.

Un channel est représenté comme un chemin sous la forme /foo/bar/... et doit systématiquement commencer par un /. Il en existe deux types : ceux définis par l’application et ceux réservés par le protocole. Ces derniers commencent toujours par /meta/. Dans le cas du handshake, le channel doit être /meta/handshake.

La version doit correspondre au numéro de version du protocole. 1.0 ici.

Le paramètre supportedConnectionTypes contient la liste des types de transports supportés. Bien que nous ayons dit plus haut que nous emploierons du long-polling, nous positionnerons la valeur ["long-polling", "callback-polling"]. Ceci simplement parce que si nous souhaitons implémenter le callback-polling nous n’aurons pas de modification à faire ;)

Voici donc à quoi ressemblera la méthode de handshake :

module Faye
  class Client
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
      @clientId = nil
      @interval = nil
 
      # ...
 
    end
 
    # ...
 
    def handshake
      id = Faye.random(32)
      message = {
        "channel" => Faye::Channel::HANDSHAKE,
        "version" => Faye::BAYEUX_VERSION,
        "supportedConnectionTypes" => [ "long-polling", "callback-polling" ],
        "id" => id
      }
 
      response = send( message )[0]
      if response["successful"] and response["id"] == id
        @clientId = response["clientId"]
        @interval = response["advice"]["interval"]
      else
        raise
      end
    end
 
    # ...
 
  end
end

Dans cette méthode j’utilise Faye::Channel::HANDSHAKE et Faye::BAYEUX_VERSION, deux constantes déclarées dans faye. Si vous souhaitez être indépendant de ce dernier, vous pouvez remplacer ces valeurs par celle que j’ai indiquée. Vous noterez également que j’ai ajouté dans le message le paramètre optionnel id. Ce paramètre permettra de valider, dans certains cas, que la réponse que nous recevons est bien celle attendu. En effet, si en retour nous retrouvons ce même ID c’est que, à priori tout va bien. Je dis bien « à priori »…

Je vous ai indiqué que la raison d’être de ce handshake était de récupérer un identifiant client. C’est ce que nous faisons en parsant la réponse. Cette réponse peut avoir deux structures différentes en fonctions ou non de la présence d’erreur. Je ne détaillerai pas la structure complète, retenez seulement quand dans le cas présent nous devons avoir récupéré les données suivantes :

• successful : suffisament parlant je pense ;)
• id : qui doit correspondre à l’ID envoyé.
• clientId : le clientId a utiliser par la suite.

Je ne parlerai pas de la valeur interval que je récupère simplement en pensant à une prochaine évolution de ce petit développement…

Connexion

La connexion se fait en envoyant un message contenant les données suivantes :

• channel : dans le cas d’une connexion nous utiliserons /meta/connect qui sera ici récupéré via la constante Faye::Channel::CONNECT.
• clientId : est la valeur récupérée lors du handshake
• connectionType : je n’y reviens pas, mais vous l’avez compris, nous faisons du long-polling.
• id : là encore, ce n’est que mimétisme.

Voici donc comment nous pouvons implémenter cela :

module Faye
  class Client
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
      @clientId = nil
      @interval = nil
 
      # ...
 
    end
 
    # ...
 
    def connect
      id = Faye.random(32)
      message = {
        "channel" => Faye::Channel::CONNECT,
        "clientId" => @clientId,
        "connectionType" => "long-polling",
        "id" => id
      }
      r = send( message )
 
      # ...
 
    end
  end
end

A ce niveau, si vous faites un petit test, vous vous rendrez compte que la connexion attend une réponse de la part du serveur. En effet cette connexion attend que le bus Comet envoie des données. C’est ainsi que nous simulons le push ! Ce sont ces données que nous devrons donc traiter en fonction des souscriptions.

Pour savoir si le retour est exact, nous devons retrouver dans la structure JSON le champ successful à true et le champ id avec la même valeur que celle envoyée.

Si tout se passe bien, alors nous pouvons récupérer les données du message dans la structure data :

module Faye
  class Client
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
      @clientId = nil
      @interval = nil
 
      # ...
 
    end
 
    # ...
 
    def connect
      id = Faye.random(32)
      message = {
        "channel" => Faye::Channel::CONNECT,
        "clientId" => @clientId,
        "connectionType" => "long-polling",
        "id" => id
      }
      r = send( message )
 
      if r[0]["id"] == id and r[0]["successful"] == true
 
        # traitement du message contenu dans r[1]["data"] pour la souscription au channel r[1]["channel"]
        # ...
 
      elsif r[0]["successful"] == false
 
        # ...
 
      end
 
      # ...
 
    end
 
    # ...
 
  end
end

Nous verrons au paragraphe souscription comment traiter le message de réponse. Avant cela, détaillons ce que nous devons faire en cas d’échec. Le protocole Bayeux nous indique que dans un tel cas, il faut refaire un handshake puis refaire la connexion. Cependant, comme la connexion elle-même est bloquante, dans le sens où elle attend une réponse, il serait bon de l’isoler dans un thread afin de permettre le déroulement de notre programme. De plus, si la connexion est un succès, une fois le message traité, il faut en rouvrir une de façon à se remettre en attente d’un nouveau push du serveur. Pour cela nous pouvons placer la connexion dans une boucle infinie.

Voici donc comment nous allons gérer cela :

module Faye
  class Client
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
      @clientId = nil
      @interval = nil
      @connection = nil
 
      # ...
 
    end
 
    # ...
 
    def connect
      @connection.kill unless @connection.nil?
      @connection = Thread.new {
        faild = false
        while true
          id = Faye.random(32)
          message = {
            "channel" => Faye::Channel::CONNECT,
            "clientId" => @clientId,
            "connectionType" => "long-polling",
            "id" => id
          }
          r = send( message )
 
          if r[0]["id"] == id and r[0]["successful"] == true
 
            # traitement du message contenu dans r[1]["data"] pour la souscription au channel r[1]["channel"]
            # ...
 
          elsif r[0]["successful"] == false
            faild = true
            break
          end
        end
 
        if faild
          handshake()
          connect()
        end
      }
    end
 
    # ...
 
  end
end

Souscription

La souscription se fait pour un ou plusieurs channels avec, en second paramètre, la méthode qui doit être utilisée pour traiter les massages venant de ces channels. Nous avons déjà parlé des channels. Bien entendu dans le cas présent il s’agira de channels spécifiques à l’application. Concernant le callback, nous utiliserons un block.

Le message envoyé au bus Comet doit contenir les informations suivantes :

• channel : il ne s’agit pas, ici, du channel auquel nous souhaitons souscrire, mais celui utilisé par le protocole pour déclarer une souscription : /meta/subscribe, ou, dans notre cas ou nous utilisons faye : Faye::Channel::SUBSCRIBE.
• clientId : le client ID récupéré lors du handshake.
• subscription : ce paramètre prend en valeur un tableau des channels auxquels nous souhaitons souscrire.
• id : l’id du message.

Comme vous pouvez le voir, nulle part nous ne stockons le callback à utiliser pour traiter les messages renvoyés. C’est normal puisque le bus Comet n’en à que faire puisqu’il seront exécutés côté client. Il nous appartient donc de les stocker. Nous ferons cela en mettant en place un hashage ayant pour clé le channel et comme valeur le block.

module Faye
  class Client    
    def initialize( uri_or_string )
      @uri = uri_or_string
      @uri = URI.parse(@uri) if @uri.class == String
      @clientId = nil
      @interval = nil
      @connection = nil
      @subscriptions = {}
    end
 
    # ...
 
    def subscribe( channels, &block )
      channels = [channels] unless channels.class == Array
      if block
        channels.each do |c|
          @subscriptions[c] = block
        end
      end
      message = {
        "channel" => Faye::Channel::SUBSCRIBE,
        "clientId" => @clientId,
        "subscription" => channels,
        "id" => Faye.random(32)
      }
 
      r = send(message)
    end
 
    # ...
 
  end
end

Je ne prends pas la peine de gérer le retour. Ce n’est pas bien !

Connexion

Nous pouvons maintenant revenir sur la connexion afin de traiter les messages. Il suffit donc de passer le message au block correspond au channel qui l’a poussé :

    # ...
 
    def connect
      @connection.kill unless @connection.nil?
      @connection = Thread.new {
        faild = false
        while true
          id = Faye.random(32)
          message = {
            "channel" => Faye::Channel::CONNECT,
            "clientId" => @clientId,
            "connectionType" => "long-polling",
            "id" => id
          }
          r = send( message )
 
          if r[0]["id"] == id and r[0]["successful"] == true
            @subscriptions[r[1]["channel"]].call( r[1]["data"])
          elsif r[0]["successful"] == false
            faild = true
            break
          end
        end
 
        if faild
          handshake()
          connect()
        end
      }
    end
 
    # ...

Publication

La publication se fait par l’envoi d’un message contenant les champs suivants :

• channel : le channel destinataire du message.
• data : les données, sous forme d’une structure JSON.
• clientId : le fameux client ID.
• id : par habitude ;)

Ceci nous donne donc le code suivant :

module Faye
  class Client
 
    # ...
 
    def publish( channel, data )
      message = [
        {
          "channel" => channel,
          "data" => data, 
          "clientId" => @clientId,
          "id" => Faye.random(32)
        }
      ]
      r = send(message)[0]
    end
 
    # ...
 
  end
end

Encore une fois, je ne prends pas le temps de traiter la réponse… Encore une fois, ce n’est pas bien !!!

… et leur contraire

Là où il y a connexion, il y a forcement « déconnexion », de même la où il y a souscription, il y a désabonnement. Je pense que vous avez compris le principe, et je me permets donc de vous livrer sans autre explication les méthodes correspondantes :

module Faye
  class Client
 
    # ...
 
    def disconnect
      unless @connection.nil?
        @connection.kill 
        message = {
          "channel" => Faye::Channel::DISCONNECT,
          "clientId" => @clientId,
          "id" => Faye.random(32)
        }
        r = send( message )
      end
    end
 
    # ...
 
    def unsubscribe( channels )
      channels = [channels] unless channels.class == Array
      channels.each do |c|
        @subscriptions.delete(c)
      end
      message = {
        "channel" => Faye::Channel::UNSUBSCRIBE,
        "clientId" => @clientId,
        "subscription" => channels,
        "id" => Faye.random(32)
      }
 
      r = send(message)
    end
 
    # ...
 
  end
end

Let’s play !

Maintenant que nous avons notre librairie cliente, nous pouvons développer un petit client en ligne de commande pour soapbox.

x = Faye::Client.new( 'http://localhost:3000/comet' )
 
puts "-- handshake"
x.handshake
 
puts "-- subscriptions"
x.subscribe( "/mentioning/daemon" )
 
x.subscribe( "/from/greg" ) { |r|
  puts "#{r["user"]} : #{r["message"]}"
}
 
puts "-- connect"
x.connect
 
msg = ""  
while msg != "quit"
  msg = $stdin.readline.chomp
  unless msg == "quit"
    channel = "/from/daemon"
    data = { "user" => "daemon", "message" => msg }
    r = x.publish( channel, data )
    unless r["successful"]
      puts "=> Message not send !"
    end
  end
end
 
x.disconnect

Bon, OK, c’est très très rudimentaire, mais vous avez compris ! Et le principal c’est que cela fonctionne :

A+

Attention, n’oubliez pas la remarque faite sur la page du projet faye : it’s a toy. Donc, tout comme ce qui précède, n’utilisez pas cela en production⁴. Et bien cela s’applique, à plus forte raison, à ce qui est écrit ci-dessus. Maintenant, si vous êtes joueur, vous pouvez récupérer cela dans les sources de Capcode ou ici.

Notez que si je me suis attaché à faye, ce petit client devrait pouvoir fonctionner avec toute solution Comet respectant le protocole Bayeux.

¹ Merci !
² :P
³ Ca peut paraitre idiot, cela n’en reste pas moins vrai !
⁴ On vous aura prévenu !

Notifications ?

Une notification intervient quand un serveur envoie des données au client quand il en a envie, et donc sans aucune demande du client. En dehors du Web, tous les systèmes de messagerie instantanés, par exemple, fonctionnent sur ce principe. Mais de par son côté stateful, le protocole HTTP ne permet pas ce genre de chose. Faux ! me direz-vous. La preuve par Google, ou plutôt Google Mail qui non seulement ne nous oblige pas à reloader sa page pour découvrir de nouveaux messages, mais qui en plus propose un service de messagerie instantanée aussi efficace que n’importe quel Skype ou MSN ! Et bien malheureusement, c’est vrai. Et si nous arrivons à faire de la notification via le Web ce n’est que par le truchement de bidouillages plus ou moins subtils qui vont permettre de le simuler. Depuis plusieurs années, nous désignons les mécanismes permettant de faire du push HTTP sous le terme Comet, inventé par Alex Russell.

Comet

Comet est une désignation peu claire. En effet, personne ne sait très bien ce que recouvre ce terme. Globalement on lui attribut tous les mécanismes permettant de faire de la notification.

Oui mais comment faire cela justement ?

Dans son fonctionnement classique, un serveur HTTP attend une requête du client et renvoie une réponse :

Avec AJAX, nous avons rajouté, côté client, une couche entre l’utilisateur et le serveur. C’est elle qui reçoit les demandes du client, qui les transmet au serveur, qui reçoit la réponse, et elle se charge de mettre à jour la page. Ceci fait que les chargements sur la page ne sont pas forcement synchronisés avec les échanges qui ont lieu entre le moteur AJAX et le serveur :

Cela permet ainsi de mettre à jour des informations dans la page sans tout recharger. Avec AJAX, nous pouvons déjà simuler un comportement de notifications. En effet, il suffit de demander au moteur AJAX d’envoyer une requête, à intervalle régulier au serveur, et si ce dernier à une nouvelle information, de l’afficher. Mais ce n’est pas du Comet. En effet, dans ce cas, ce n’est pas le serveur qui est à l’initiative de l’envoi de données. De plus, l’envoi de données par le serveur est rythmé par les demandes du client. Et même si elles peuvent être très rapprochées, elles ne donneront pas toujours le même sentiment de fluidité que nous retrouverons avec un Comet bien fait.

Avec Comet, nous allons remplacer le serveur AJAX pas un client Comet qui se placera entre le client et le serveur. Côté serveur, nous allons placer un bus Comet chargé de communiquer avec le service :

Côté client, la connexion Comet est initialisée. A partir de là, le service enverra des évènements au bus Comet qui se chargera d’envoyer les informations nécessaires au client Comet qui à son tour mettra à jour la page Web. Bien entendu le client peut lui même envoyer de l’information au service par l’intermédiaire du client puis du bus Comet. Vous l’aurez compris, nous utilisons aussi de l’AJAX. Quant au service, cela peut être n’importe quoi : un service de messagerie instantané, un serveur de données, … bref n’importe quel service capable lui-même de pousser des données.

Capcode

Avec Capcode nous pouvons faire du Comet en utilisant un middleware Rack. Personnellement j’en ai trouvé 2 : Pusher et faye. Bien qu’un peu moins aboutit que le premier, je vous propose d’utiliser faye.

faye arrive avec un exemple sous forme de messagerie instantanée à la Twitter. Pour valider le fonctionnement de faye avec Capcode, je vous propose d’adapter cet exemple.

soapbox est écrit comme une application Sinatra. Le code de l’application est minimaliste :

require 'rubygems'
require 'sinatra'
 
get '/' do
  @server = env['faye.server']
  erb :index
end

La seule chose remarquable ici est le fait que lors de l’accès à la racine de l’application, le serveur et modifié pour devenir le serveur faye et que nous renvoyons la page index.erb. Transformer cela en code Capcode est ultra simple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14

require 'rubygems'
require 'capcode'
require 'capcode/render/erb'
 
module Capcode
  set :erb, "views"
 
  class Index < Route '/'
    def get
      @server = env['faye.server']
      render :erb => :index
    end
  end
end

Pour respecter ce qui est fait, nous créons un répertoire views dans lequel nous placerons les templates Erb, tout cela sans oublié de le déclarer (ligne 6).

Si nous regardons maintenant le fichier de configuration pour Rack, nous avons cela :

dir = File.dirname(__FILE__)
 
require dir + '/../../lib/faye'
require dir + '/app'
 
use Faye::RackAdapter, :mount => '/comet'
run Sinatra::Application

Ajouter cela dans Capcode est là encore trivial :

require 'rubygems'
require 'capcode'
require 'capcode/render/erb'
require 'faye'
 
module Capcode
  set :erb, "views"
  use Faye::RackAdapter, :mount => '/comet'
 
  class Index < Route '/'
    def get
      @server = env['faye.server']
      render :erb => :index
    end
  end  
end

Si maintenant nous regardons le template Erb nous voyons qu’il utilise une CSS et trois fichiers JavaScript :

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
<html>
<head>
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <title>Faye demo: chat client</title>
  <link rel="stylesheet" href="/style.css" type="text/css" media="screen">
  <script src="/jquery.js" type="text/javascript"></script>
  <script src="/comet.js" type="text/javascript"></script>
  <script src="/soapbox.js" type="text/javascript"></script>
</head>
<body>
<div class="container">
...

Les fichiers style.css, jquery.js et soapbox.js se trouvent dans le répertoire public. Nous devons donc créer ce même répertoire et déclarer son existence dans Capcode :

require 'rubygems'
require 'capcode'
require 'capcode/render/erb'
require 'faye'
 
module Capcode
  set :erb, "views"
  set :static, "public"
  use Faye::RackAdapter, :mount => '/comet'
 
  class Index < Route '/'
    def get
      @server = env['faye.server']
      render :erb => :index
    end
  end  
end

Puis nous modifions le template Erb :

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
<html>
<head>
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <title>Faye demo: chat client</title>
  <link rel="stylesheet" href="/public/style.css" type="text/css" media="screen">
  <script src="/public/jquery.js" type="text/javascript"></script>
  <script src="/comet.js" type="text/javascript"></script>
  <script src="/public/soapbox.js" type="text/javascript"></script>
</head>
<body>
<div class="container">
...

Oui, mais le fichier comet.js ??? Et bien si vous regardez la documentation de faye, vous verrez que le simple fait de déclarer l’utilisation du middleware faye met automatiquement en place un bus Comet accessible via la route /comet et met à disposition la librairie JavaScript cliente via la route /comet.js. Donc, nous n’avons rien de plus à faire pour ce fichier.

Vous pouvez maintenant démarrer l’application et tester :

Cet exemple a été ajouté dans les sources de Capcode.

Toute l’intelligence de l’exemple se trouve non seulement fans faye mais également dans le fichier soapbox.js que je vous engage vivement à regarder, tout comme la documentation de faye.

Contrairement à ActiveRecord, Sequel n’a pas été développé pour un framework. Ce n’est pas non plus (initialement) un ORM, mais une librairie d’accès pour des bases de données, un peu comme DBI. Cependant, contrairement à ce dernier, il se rapproche de DataMapper ou ActiveRecord par sont côté SQL dissimulé. Bref, Sequel se situe entre DBI et ActiveRecord/DataMapper.

Voici un petit exemple :

require "rubygems"
require "sequel"
 
# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
# Création d'une table 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end
 
# Ajout de données dans la table
DB[:users].insert( :login => 'Muriel', :password => 'leiruM' )
DB[:users].insert( :login => 'Greg', :password => 'gerG' )
 
# Affichage du contenu de la table 
DB[:users].all.each do |record|
  puts "#{record[:login]} : #{record[:password]}"
end

J’ai dit un peu plus haut que Sequel n’était pas un ORM. Ce n’est pas tout à fait vrai. En effet, il offre la possibilité d’être utilisé comme tel :

require "rubygems"
require "sequel"
 
# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
# Création d'une table 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end
 
# Mapping
class User < Sequel::Model
end
 
# Ajout de données dans la table
User.insert( :login => 'Muriel', :password => 'leiruM' )
User.insert( :login => 'Greg', :password => 'gerG' )
 
# Affichage du contenu de la table 
User.all.each do |record|
  puts "#{record.login} : #{record.password}"
end

Bon, mais quel est l’objectif recherché me demanderez-vous ? Et bien simplement de palier à certains petits défauts de conception qui me dérange dans Sequel.

Déclaration des modèles

Il est impossible dans Sequel de déclarer un modèle si la table correspondante n’existe pas, ou, tout au moins, si la connexion à la base n’a pas été faite avant cette déclaration. Ainsi, faire ceci provoque une erreur :

# Mapping
class User < Sequel::Model
end
 
# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end
 
# => Sequel::Error: No database associated with Sequel::Model

Si par contre nous faisons la connexion avant, cela semble fonctionner :

# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
# Mapping
class User < Sequel::Model #:users
end
 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end

Je dis bien semble, car en fait le comportement de la classe User n’est pas le même si la table existe avant la déclaration du modèle. Ainsi, si vous faites ceci :

# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end
 
# Mapping
class User < Sequel::Model
end

Vous pourrez utiliser la classe User en considérant les champs de la table users comme des accesseurs de cette classe :

User.all.each do |user|
  puts user.login
  puts user.password
end

Si par contre vous créez la table après avoir déclaré le modèle, votre classe User n’a plus le même comportement et vous devez passer par la méthode values de la classe User qui renvoie un hashage des données :

# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
# Mapping
class User < Sequel::Model #:users
end
 
DB.create_table :users do
  primary_key :id
  String :login
  String :password
end
 
# ...
 
# Affichage du contenu de la table 
User.all.each do |record|
  puts record.values[:login]
  puts record.values[:password]
end

Tout cela n’est pas très rigoureux et pas réellement exploitable.

Création de table et migration

Pour la création des tables, là encore j’ai un problème. En effet, comme vous avez pu le constater, la méthode create_table est une méthode d’instance de Sequel::Database récupérée via une connexion (Sequel.connect). Ceci implique que nous ne pouvons proposer un schéma de table qu’après avoir initialisé la connexion à la base. Si cela semble tout à fait logique, cela peut entrainer pas mal de contraintes dans certains cas. Oui, mais pas avec Capcode ! Effectivement, les méthodes Capcode.run et Capcode.application prenant en paramètre un bloc, il est possible de créer les tables dans ce bloc. Cependant, cela rompt avec la philosophie souhaitée pour l’utilisation de ce bloc¹ qui veut que l’on réserve ce bloc pour y placer des éléments de configuration de l’application (remplissage de table, …) et non pas du code pour l’application.

Si vous avez l’habitude d’utiliser ActiveRecord ou DataMapper ce type de problème ne vous aura jamais dérangé parce que dans le premier cas vous utilisez les migrations, et donc vous générez le schéma à priori, et dans le second, le schéma fait partie intégrante du modèle et il est donc créé automatiquement².

Heureusement³ Sequel offre la possibilité d’utiliser des migrations. Pour cela, vous avez plusieurs solutions. Soit définir vos migrations dans des fichiers et utiliser l’option -m de l’outil sequel, soit utiliser la méthode apply de Sequel::Migration. Grâce à cette dernière possibilité, nous pouvons résoudre le problème évoqué en décrivant le schéma dans une migration et en faisant la migration juste après la connexion :

require "rubygems"
require "sequel"
 
# Chargement de l'extension permettant les migrations
Sequel.extension :migration
 
# Migration
class CreateUser < Sequel::Migration
  def up
    create_table :users do
      primary_key :id
      String :login
      String :password
    end
  end
 
  def down
    drop_table :users
  end
end
 
# Connection à une base SQLite 
DB = Sequel.connect( "sqlite://test.db" )
 
# Mise en place du schéma
CreateUser.apply( DB, :up )

So what ?

Avec tout ce que nous venons de voir, nous sommes en mesure de mettre en place une classe mimant ce que nous avons fait avec ActiveRecord mais pour Sequel. Donc nous pouvons repartir d’un exemple similaire⁴ :

require 'rubygems'
require 'sq'
 
# Mise en place des migrations (versionnées)
class CreateUsers < SQ::Schema 1.0
  def up
    create_table :users do
      String :login
      String :password
    end
  end
 
  def down 
    drop_table :users
  end
end
 
class CreatePosts < SQ::Schema 1.1
  def up
    create_table :posts do
      String :title
      String :body
    end
  end
 
  def down 
    drop_table :posts
  end
end
 
# Création des modèles
class User < SQ::Model
end
 
# Connexion
SQ.db_connect( "test.yml", "test.log" )
 
# Utilisation
User.insert(:login => 'Muriel', :password => 'leiruM')
User.insert(:login => 'Greg', :password => 'gerG')
 
User.each do |d|
  puts u[:login]
end

La mise en place des schémas est quasiment identique à ce que nous avons fait avec ActiveRecord et nous allons encore une fois déclarer une méthode de classe qui renverra une classe qui sera, dans le cas présent, de type Sequel::Migration. Par la suite, dans la méthode de connexion (SQ.db_connect), nous suivrons exactement le même procédé que celui imaginé pour ActiveRecord, en s’adaptant juste au comportement de Sequel :

module SQ
  class << self
    def Schema( n )
      @final = [n, @final.to_f].max
      m = (@migrations ||= [])
      Class.new(Sequel::Migration) do
        meta_def(:version) { n }
        meta_def(:inherited) { |k| m << k }
      end
    end
 
    def db_connect( dbfile, logfile )
      dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
      dbconfig[:adapter] = "sqlite" if dbconfig[:adapter] == "sqlite3"
      version = dbconfig.delete(:schema_version) { |_| @final }
 
      db = Sequel.connect(@cnx)
 
      if @migrations
        db.create_table? :schema_table do
          Float :version
        end
        si = db[:schema_table].first || (db[:schema_table].insert(:version => 0); {:version => 0})
        @migrations.each do |k|
          k.apply(db, :up) if si[:version] < k.version and k.version <= version
          k.apply(db, :down) if si[:version] >= k.version and k.version > version
        end
        db[:schema_table].where(:version => si[:version]).update(:version => version)
      end
    end
  end
end

Nous allons cependant devoir faire quelques adaptations mineures dans ce code pour régler le cas des modèles. Il n’est en effet pas possible d’utiliser les modèles proposés par Sequel, mais ceci ne nous empêche pas de les mimer. Pour cela nous allons créer de toutes pièces la classe SQ::Model et nous ferons en sorte qu’elle réponde, via ses méthodes de classe, aux mêmes méthodes que Sequel::Dataset. Par example la classe User répondra aux même méthodes que DB[:users]. Or :users == User.to_s.tableize.to_sym, ce qui rende la mise en place de la classe SQ::Model extrêmement simple :

module SQ
  class Model
    def self.method_missing( name, *args, &block )
      if block_given?
        SQ::db[self.to_s.tableize.to_sym].__send__(name.to_sym, *args, &block)
      else
        SQ::db[self.to_s.tableize.to_sym].__send__(name.to_sym, *args)
      end
    end
  end
end

Le seul élément vraiment remarquable dans ce code est l’utilisation de SQ::db sensé représenter la connexion. Et c’est là que nous devons modifier le code de la partie schéma pour permettre de partager la connexion au sein du module SQ. Pour cela nous mettons en place la méthode suivante :

module SQ
  class << self
    def db
      @db ||= Sequel.connect(@dbconfig)
    end
  end
end

Puis nous supprimons la ligne db = Sequel.connect(@cnx) dans SQ::db_connect, nous remplaçons partout l’utilisation de la variable db par SQ::db et nous modifions la variable dbconfig en la passant en variable d’instance. Finalement, le code complet est le suivant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

begin
  require 'sequel'
  Sequel.extension :migration
  Sequel.extension :inflector
rescue LoadError => e
  raise LoadError, "Sequel ne doit pas être installé : #{e.message}"
end
 
class Object
  def meta_def(m,&b)
    (class<<self;self end).send(:define_method,m,&b)
  end
end
 
class Hash
  def keys_to_sym
    self.each do |k, v|
      self.delete(k)
      self[k.to_s.to_sym] = v
    end
  end
end
 
module SQ
  class Model
    def self.method_missing( name, *args, &block )
      if block_given?
        SQ::db[self.to_s.tableize.to_sym].__send__(name.to_sym, *args, &block)
      else
        SQ::db[self.to_s.tableize.to_sym].__send__(name.to_sym, *args)
      end
    end
  end
 
  class << self
    def db
      @db ||= Sequel.connect(@dbconfig)
    end
 
    def Schema( n )
      @final = [n, @final.to_f].max
      m = (@migrations ||= [])
      Class.new(Sequel::Migration) do
        meta_def(:version) { n }
        meta_def(:inherited) { |k| m << k }
      end
    end
 
    def db_connect( dbfile, logfile )
      @dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
      @dbconfig[:adapter] = "sqlite" if @dbconfig[:adapter] == "sqlite3"
      version = dbconfig.delete(:schema_version) { |_| @final }
 
      if @migrations
        SQ::db.create_table? :schema_table do
          Float :version
        end
        si = SQ::db[:schema_table].first || (SQ::db[:schema_table].insert(:version => 0); {:version => 0})
        @migrations.each do |k|
          k.apply(SQ::db, :up) if si[:version] < k.version and k.version <= version
          k.apply(SQ::db, :down) if si[:version] >= k.version and k.version > version
        end
        SQ::db[:schema_table].where(:version => si[:version]).update(:version => version)
      end
    end
  end
end

Notez que nous utilisons l’extension inflector afin de pouvoir utiliser la méthode String.tableize et que nous prenons en compte (ligne 51) le fait que Sequel permet d’utiliser SQLite en nommant sont adaptateur sqlite là ou les autres utilisent sqlite3.

Voilà, tout ceci a été mis en place dans Capcode et un petit example illustre comment l’utiliser.

¹ Laquelle ?
² Tout ceci est extrêmement schématique, je sais, mais je ne m’étendrais pas plus sur le sujet.
³ Faudrait savoir ! Un coup on aime, un coup on aime pas les migrations !
⁴ Pour des questions de bonne compréhension, nous placerons notre code dans le module SQ là ou nous utilisions AR…

Et alors, ce besoin a des impacts non négligeables sur le développement de certaines fonctions. Je ne vais pas entrer dans les détails de la sécurisation d’une prescription, mais juste vous dire que pour la prise en compte de l’état pathologique d’un patient, nous codons cet état via la CIM. Or l’utilisation de cette classification, et plus fortement sa diffusion, est soumise à une licence payante pour chaque pays. Or VIDAL n’ayant acquis qu’une licence pour la France, les versions internationales de la base n’intègrent pas les libellés de la CIM. Tout mon problème était de savoir comment permettre de travailler avec ces libellés quand la démo se fait à l’international ? Plus précisément, comment faire en sorte qu’une personne ayant acquis la licence puisse utiliser mon outil avec sa CIM.

Initialement, j’avais opté pour une solution consistant à déporter la classification dans une base SQLite ne contenant qu’une seule table avec trois colonnes :

Par défaut cette base ne contenait que les codes CIM sans les libellés. Il suffisait, localement, de remplacer le fichier SQLite pour pouvoir accéder aux libellés.

Tout cela était sans compter sur le fait que les personnes qui ont besoin de cet outil ont souvent une approche technique proche de l’état larvaire, et que leur demander de créer un fichier SQLite, aussi simple soit-il, tient du roman de science-fiction chez certains². J’ai donc dû chercher du côté des outils plus classiques de cette population chez qui Excel est un prolongement synaptique. J’ai alors découvert que ce merveilleux outil est capable de générer des fichiers XML. Sauvé³ !

Maintenant que nous savons que nous pouvons utiliser du XML, un simple fichier formaté comme ce qui suit suffit :

<cims>
  <cim10>
    <code>A00.-</code>
    <parent></parent>
    <label>Cholera</label>
  </cim10>
  <cim10>
    <code>A00.0</code>
    <parent>A00.-</parent>
    <label>Choléra classique</label>
  </cim10>
 
  ...
</cims>

Parcourir un fichier XML est une chose relativement facile avec Ruby. Il existe un grand nombre de modules pour nous y aider. Dans le cas présent, j’ai choisis HappyMapper. Ce dernier permet mapper du XML dans des objets. Ainsi, avec le fichier XML des codes CIM, il suffit de créer l’objet suivant :

class Cim10
  include HappyMapper
 
  element :code, String
  element :parent, String
  element :label, String
end

Si ensuite nous parsons le contenu du fichier XML (via Cim10.parser nous obtenons un tableau d’objets Cim10 :

cims = Cim10.parse(File.read("cim10-fr.xml"))

Tout le problème maintenant c’est de pouvoir faire des recherches dans ce tableau. Pour cela je me suis amusé à transformer le tableau de sortie en utilisant une nouvelle classe : HappyArray :

require "rubygems"
require "active_record/dynamic_finder_match"
 
class HappyArray < Array
  def find( h )
    r = HappyArray.new
    self.each do |cim|
      keep = true
      h.each do |k, v|
        term = v
        term = v.join('|') if v.class == Array
        keep = keep && !(cim.send(k).downcase.match(term.downcase).nil?)
      end
      r << cim if keep
    end
    return r
  end
 
  def method_missing(method_name, *args, &block)
    if match = ActiveRecord::DynamicFinderMatch.match( method_name )
      finder = {}
      match.attribute_names.each do |f|
        finder[f.to_sym] = args.shift
      end
      return find( finder )
    end
    return HappyMapper.new
  end
end

Cette classe me permet ainsi de faire ceci :

cims = Cim10.parse(File.read("cim10-fr.xml"))
happyCims = HappyArray.new(cims)
 
results = happyCims.find( :label => "choléra" )
# => Tableau des objets Cim10 dont le libellé contient le terme "choléra"
 
results = happyCims.find_by_label_and_code( ["choléra", "vaccin"], "A00" )
# => Tableau des objets Cim10 dont le libellé contient "choléra" ou "vaccin" et dont le code contient "A00"

Je n’ai pas voulu ajouter les méthodes de la classe HappyArray à la classe Array car finalement elles ne peuvent servir que dans le cas d’une utilisation avec HappyMapper. La question maintenant c’est de savoir si je sécurise un peu ce code et le propose comme patch pour HappyMapper ou pas ?

¹ Vous pouvez aussi regarder ceci ;)
² Suivez mon regard…
³ Enfin presque… Le problème, maintenant, va être d’expliquer comment faire :(

ActiveRecord

Pour utiliser ActiveRecord nous avons besoin d’au moins² deux choses : un schéma et un modèle. En général les schémas sont mis en place via les migrations. Pour cela, Rails créés dans le répertoire db/migrate des fichiers définissant des classes héritant de ActiveRecord::Migration. Les modèles sont, eux, placés dans le répertoire app/models de l’application Rails. Ils définissent des classes héritant d’ActiveRecord::Base. En général, modèles et migrations sont créés en même temps. Quand vous créez un modèle, Rails génère en même temps une migration :

$ ruby script/generate model user
      exists  app/models/
      exists  test/unit/
      exists  test/fixtures/
      create  app/models/user.rb
      create  test/unit/user_test.rb
      create  test/fixtures/users.yml
      create  db/migrate
      create  db/migrate/20091106191317_create_users.rb
$

Le fichier de migration ainsi généré contiendra le code suivant :

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
 
      t.timestamps
    end
  end
 
  def self.down
    drop_table :users
  end
end

Le fichier du modèle sera lui beaucoup plus court :

class User < ActiveRecord::Base
end

Si nous voulons utiliser notre modèle, il faut maintenant faire deux petites choses.

1. Compléter le schéma

En fait de schéma, c’est bien au fichier de migration que je pense. En effet, pour le moment notre table users ne contient que les champs de timestamps, et il faut donc y ajouter les champs permettant de définir un utilisateur.

2. Faire la migration

Pour cela il faut lancer un rake db:migrate

Une fois cela fait, nous pouvons utiliser le modèle User dans nos contrôleurs.

Comme vous avez dû le comprendre au début de ce post, je trouve tout cela un peu lourd. Non seulement il faut, exploser les choses en une multitude de fichiers, mais il faut en plus un Rackfile. En ce qui me concerne j’aimerai pouvoir lancer une application Ruby utilisant ActiveRecord, que la base soit créée (ou mise à jour) s’il y a besoin, et tout cela, en ayant la possibilité de tout mettre dans un seul fichier… Bref, idéalement je voudrais pouvoir faire cela :

require 'rubygems'
require 'active_record'
 
class DBSchema < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string :login
      t.string :password
    end
  end
 
  def self.down 
    drop_table :users
  end
end
 
class User < ActiveRecord::Base
end
 
ActiveRecord::Base.establish_connection( "test.yml" )
 
User.new( :login => "Muriel", :password => "leiruM" ).save
User.new( :login => "Greg", :password => "gerG" ).save
 
User.all.each do |u|
  puts u.login
end
# => Muriel
# => Greg

Malheureusement, ce n’est pas possible³. J’ai donc développé une petite surcouche permettant de faire ceci :

require 'rubygems'
require 'ar'
 
class DBSchema < AR::Schema 1.0
  def self.up
    create_table :users do |t|
      t.string :login
      t.string :password
    end
  end
 
  def self.down 
    drop_table :users
  end
end
 
class User < AR::Model
end
 
AR.db_connect( "test.yml", "test.log" )
 
User.new( :login => "Muriel", :password => "leiruM" ).save
User.new( :login => "Greg", :password => "gerG" ).save
 
User.all.each do |u|
  puts u.login
end
# => Muriel
# => Greg

Création du schéma

Comme vous pouvez le voir, je n’utilise pas ActiveRecord::Migration mais AR::Schema, ce qui semble plus logique puisqu’il s’agit bien de définir un schéma de base. Notez que ce schéma est défini avec un numéro de version⁴. Pour faire cela, nous allons faire un peu de métaprogrammation. Dans les faits, AR::Schema n’est pas un classe, mais une méthode de classe qui renvoie une classe de type ActiveRecord::Migration :

module AR
  # ...
 
  def self.Schema( n )
    @final = [n, @final.to_f].max
    m = (@migrations ||= [])
    Class.new(ActiveRecord::Migration) do
      meta_def(:version) { n }
      meta_def(:inherited) { |k| m << k }
    end
  end
 
  # ...
end

Dans la classe de type ActiveRecord::Migration que nous renvoyons, nous définissons deux méthodes de classes : version et inherited. La première sert à stocker la version du schéma. La seconde est utilisée pour mettre à jour la liste des classes de migration définies. Ainsi si nous reprenons l’exemple ci-dessus :

class DBSchema < AR::Schema 1.0
  def self.up
    create_table :users do |t|
      t.string :login
      t.string :password
    end
  end
 
  def self.down 
    drop_table :users
  end
end

Dans AR, la variable @migrations sera égale à [DBSchema], @final sera égale à 1.0 et DBSchema.version sera égal à 1.0. Nous reviendrons plus tard sur l’intérêt de la variable @final.

Création du modèle

Là où nous avons l’habitude d’utiliser ActiveRecord::Base, je propose AR::Model. Là encore, ce n’est qu’une question de logique puisque nous définissons bien un modèle.

La mise en place d’AR::Model est on ne peut plus simple :

module AR
  Model = ActiveRecord::Base
  # ...
end

Connexion et Migration

Il ne reste plus qu’à définir la méthode AR.db_connect. Dans cette méthode, nous devons faire deux choses : créer la connexion puis appliquer les migrations.

La première partie est relativement simple et passe par l’utilisation d’ActiveRecord::Base.establish_connection.

Pour la gestion des migrations, nous avons un peu plus de travail. En effet, pour savoir si une migration s’applique (et dans quel sens (up ou down), nous devons savoir quelle version du schéma existe (s’il existe). Si vous regardez comment Rails gère cela, vous verrez que dans la base de vos applications se trouve une table schema_migrations contenant le préfixe (format AAAAMMJJHHMMSS) du fichier de migration le plus proche dans le temps. Nous allons utiliser la même méthode, mais comme nous avons pris le parti de passer un numéro de version à nos schémas, ce sont ces derniers que nous allons utiliser.

Nous devons donc créer un modèle (SchemaInfo) qui nous servira à gérer cette version, avec la table correspondante dans la base. ActiveRecord ne supportant pas de devoir créer une table si elle existe déjà, nous commencerons par vérifier sa présence :

module AR
  # ...
 
  class SchemaInfo < Model
  end
 
  class << self
    def db_connect( dbfile, logfile )
      dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
 
      # ...
 
      ActiveRecord::Base.establish_connection(dbconfig)
      ActiveRecord::Base.logger = Logger.new(logfile)
 
      if @migrations
        unless SchemaInfo.table_exists?
          ActiveRecord::Schema.define do
            create_table SchemaInfo.table_name do |t|
              t.column :version, :float
            end
          end
        end
 
        # ...
      end
    end
  end
end

Ceci étant, nous pouvons maintenant jouer avec les numéros de version. Cependant, pour pouvoir gérer pleinement
les migrations il peut être utile de préciser quelle version de schéma nous voulons utiliser. Par défaut, nous partirons du principe que c’est le schéma de plus haute version qui sera pris en compte, mais nous devons permettre de préciser la version du schéma à utiliser. Pour cela je vous propose de rajouter cette information dans le fichier de configuration de la base en y ajoutant l’item schema_version :

adapter: sqlite3
database: test.db
schema_version: 1.0

Nous pouvons maintenant récupérer ce numéro de version dans AR.db_connect :

module AR
 
  # ...
 
  class << self
    def db_connect( dbfile, logfile )
      dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
      version = dbconfig.delete(:schema_version) { |_| @final }
 
      # ...
 
    end
  end
end

Il ne reste plus qu’à lancer les migrations en fonction de la version. Ainsi, pour chaque schéma, si la version du schéma existant est inférieure à la version du schéma courant et que la version du schéma courant et inférieure ou égale à la version souhaitée, alors nous migrons vers le haut (up). Si la version du schéma existant est supérieure ou égale à la version du schéma courant et que la version du schéma courant est supérieure à la version du schéma souhaité, alors nous migrons vers le bas (down). Sinon, on ne fait rien.

Bien entendu, il ne faudra pas oublier de modifier la version du schéma dans la table d’information sur le schéma.

module AR
 
  # ...
 
  class << self
    def db_connect( dbfile, logfile )
      dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
      version = dbconfig.delete(:schema_version) { |_| @final }
 
      ActiveRecord::Base.establish_connection(dbconfig)
      ActiveRecord::Base.logger = Logger.new(logfile)
 
      if @migrations
        unless SchemaInfo.table_exists?
          ActiveRecord::Schema.define do
            create_table SchemaInfo.table_name do |t|
              t.column :version, :float
            end
          end
        end
        si = SchemaInfo.find(:first) || SchemaInfo.new(:version => 0)
        @migrations.each do |k|
          k.migrate(:up) if si.version < k.version and k.version <= version
          k.migrate(:down) if si.version >= k.version and k.version > version
        end
        si.update_attributes(:version => version)
      end
    end
  end
end

Pour terminer

Nous avons utilisé les méthodes meta_def et keys_to_sym lors de la création du module AR. Voici comment elles sont définies :

class Object
  def meta_def(m,&b)
    (class<<self;self end).send(:define_method,m,&b)
  end
end
 
class Hash
  def keys_to_sym
    self.each do |k, v|
      self.delete(k)
      self[k.to_s.to_sym] = v
    end
  end
end

Voici donc le code complet de ar.rb :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

begin
  require 'active_record'
rescue LoadError => e
  raise LoadError, "ActiveRecord ne doit pas être installé : #{e.message}"
end
 
class Object
  def meta_def(m,&b)
    (class<<self;self end).send(:define_method,m,&b)
  end
end
 
class Hash
  def keys_to_sym
    self.each do |k, v|
      self.delete(k)
      self[k.to_s.to_sym] = v
    end
  end
end
 
module AR
  Model = ActiveRecord::Base
 
  class SchemaInfo < Model
  end
 
  def self.Schema( n )
    @final = [n, @final.to_f].max
    m = (@migrations ||= [])
    Class.new(ActiveRecord::Migration) do
      meta_def(:version) { n }
      meta_def(:inherited) { |k| m << k }
    end
  end
 
  class << self
    def db_connect( dbfile, logfile )
      dbconfig = YAML::load(File.open(dbfile)).keys_to_sym
      version = dbconfig.delete(:schema_version) { |_| @final }
 
      ActiveRecord::Base.establish_connection(dbconfig)
      ActiveRecord::Base.logger = Logger.new(logfile)
 
      if @migrations
        unless SchemaInfo.table_exists?
          ActiveRecord::Schema.define do
            create_table SchemaInfo.table_name do |t|
              t.column :version, :float
            end
          end
        end
        si = SchemaInfo.find(:first) || SchemaInfo.new(:version => 0)
        @migrations.each do |k|
          k.migrate(:up) if si.version < k.version and k.version <= version
          k.migrate(:down) if si.version >= k.version and k.version > version
        end
        si.update_attributes(:version => version)
      end
    end
  end
end

Pourquoi vous avoir parlé de tout cela. Et bien simplement parce que c’est ce que j’ai mis en place dans Capcode pour pouvoir utiliser ActiveRecord⁵.

Ce code s’inspire librement de ce qui est mis en place dans Camping.

¹ Ok, par forcement pour un gros projet…
² Je dis au moins, car nous pouvons avoir plusieurs modèles
³ Notez que je conserve l’utilisation d’un fichier Yaml pour la configuration de la base.
⁴ J’avais déjà expliqué comment créer ce type de classe.
⁵ Et pourtant je déteste ActiveRecord et son principe de migration…

Comme vous le savez, Capcode est basé sur Rack et il existe pour ce dernier le projet Rack::Test, idéal pour ce que nous aider dans ce travail.

partons d’un exemple minimaliste :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# sample.rb
require 'rubygems'
require 'capcode'
 
module Capcode
  class Index < Route '/'
    def get
      render "Hello World"
    end
  end
 
  class Redir < Route '/r'
    def get
      redirect( Index )
    end
  end
end

Vous remarquerez que je n’ai volontairement pas mis l’appel à Capcode.run dans ce code. Ceci pour deux raisons. J’ai pris l’habitude de déporter cet appel dans un fichier à part ce qui me permet de créer en parallèle un fichier de configuration rackup pour le déploiement avec Passenger. De plus, Rack::Test sert à tester des applications basées sur Rack et implique d’avoir accès directement à l’application, celle-là même que vous passez à votre handler.

Rack::Test fonctionne avec Test::Unit, nous allons dons créer, pour chaque ensemble de tests, une classe héritant de Test::Unit::TestCase et nous inclurons dans cette classe le module Rack::Test::Methods :

1
2
3
4
5
6
7
8
9
10
11

# test_sample.rb
require 'rubygems'
require 'test/unit'
require 'rack/test'
 
class HomepageTest < Test::Unit::TestCase
  include Rack::Test::Methods
 
  # ...
 
end

Comme je l’ai signalé, l’utilisation de Rack::Test implique que nous ayons accès à l’application. Nous allons donc la charger et faire en sorte qu’elle soit accessible dans la classe via la méthode app :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# test_sample.rb
require 'rubygems'
require 'test/unit'
require 'rack/test'
 
require 'sample.rb'
@@app = Capcode.application( )
 
class HomepageTest < Test::Unit::TestCase
  include Rack::Test::Methods
 
  def app
    @@app
  end
 
  # ...
 
end

Nous pouvons ensuite ajouter nos tests. Chaque test est décrit dans une méthode de la classe, ces méthodes pouvant contenir autant d’assertions que nécessaire :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# test_sample.rb
require 'rubygems'
require 'test/unit'
require 'rack/test'
require 'sample.rb'
 
@@app = Capcode.application( )
 
class HomepageTest < Test::Unit::TestCase
  include Rack::Test::Methods
 
  def app
    @@app
  end
 
  def test_home
    get '/'
    assert_equal "http://example.org/", last_request.url
    assert last_response.ok?
    assert_equal "Hello World", last_response.body
  end
 
  def test_redirect
    get '/r'
    assert_equal "http://example.org/r", last_request.url
    follow_redirect!
    assert_equal "http://example.org/", last_request.url
    assert_equal "Hello World", last_response.body
  end
end

Si vous exécutez test_sample.rb vous devriez obtenir la sortie suivante :

Loaded suite /Users/greg/dev/Capcode/tests/test_sample
Started
.. 
Finished in 0.005839 seconds.
 
2 tests, 6 assertions, 0 failures, 0 errors

Pour les assertions, vous pouvez utiliser tout ce que propose Test::Unit. Pour la partie « navigation », Rack::Test vous offre les méthodes suivantes :

• get, post, put, delete et head permettent respectivement de faire des requêtes de type GET, POST, PUT, DELETE et HEAD. Chacune de ces méthodes prend en paramètre l’URI à tester, mais également les paramètres, sous forme de hachage et éventuellement des données d’environnement (également sous forme de hachage).

  post '/login', {"user" => "greg", "password" => "s3cr3t"}

• header permet de positionner la valeur d’une entête

  header "User-Agent", "Firefox"

• basic_authorize et digest_authorize permettent de donner le login et le mot de passe pour, respectivement, une authentification basic ou digest.

  digest_authorize( "greg", "p4ssw0rd" )

• follow_redirect! permet de suivre la dernière redirection renvoyée.
   
• set_cookie et clear_cookie permettent de gérer les cookies.
   
• last_request correspond à la dernière requête. C’est une instance de Rack::Request.
   
• last_response correspond à la dernière réponse, c’est une instance de Rack::MockResponse.

La sécurisation d’un serveur WebDAV passe par de l’authentification HTTP. Il existe une solution dans rack, via Rack::Auth. Malheureusement, non seulement la documentation est un élément qui fait cruellement défaut dans rack, mais en plus s’il est facile de mettre en place une authentification globale pour toute une application, c’est une autre paire de manches quand on souhaite faire cela pour une route précise. En effet, il n’est pas rare d’avoir, dans un site, une partie publique et une autre privée. Et c’est bien ce que je souhaitais permettre.

En cherchant sur Google, je suis tombé sur cet excellent post expliquant comment mettre en place une authentification Basic dans Sinatra. J’ai donc adapté la solution pour Capcode. Le problème de l’authentification Basic c’est qu’elle est plutôt réservée aux sites accessibles en HTTPS puisque les mots de passent sont en clair dans l’entête. J’ai donc fait un petit passage par la RFC2617² et en lisant attentivement le code de Rack::Auth::Digest::Request et Rack::Auth::Digest::MD5, j’ai rapidement ajouté l’authentification Digest. Ceci a donné naissance à un helper pour les controôleurs : http_authentication.

La mise en place est donc très simple. Voici un petit exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

require 'capcode'
require 'rack'
 
module Capcode
  class Private < Route '/private'    
    def get
      # Basic HTTP Authentication
      http_authentication( :type => :basic, :realm => "My Capcode test!!!" ) { 
        {
          "greg" => "toto",
          "mu" => "maia"
        }
      }
      render "Success !"
    end
  end 
 
  class Public < Route '/public'
    def get
      render "You don't need any special authorization here !"
    end
  end
end
 
Capcode.run( )

La partie importante se trouve de la ligne 8 à la ligne 13.

http_authentication permet de spécifier que vous voulez mettre en place une authentification HTTP pour le contrôleur Private. Ce helper supporte les options suivantes :

• :type qui permet de préciser le type d’authentification. Les valeurs possibles sont :basic (valeur par défaut) et :digest.
• :realm qui donne l’information sur le nom et mot de passe que peut utiliser l’utilisateur. C’est une chaine de caractère pouvant prendre n’importe quelle valeur (« Capcode.app » par défaut).
• :opaque qui est une chaîne générée par le serveur devant être retournée telle quelle par le client (defaut : « opaque »). Cette option n’est utile que dans le cas d’une authentification Digest.

Enfin, http_authentication prend en paramètre un bloc qui doit lui retourner un hachage contenant les couples login/mot de passe pouvant s’authentifier, sous la forme :

{
  "user1" => "pass1",
  "user2" => "pass2",
  # ...
}

Dans l’exemple ci-dessus, nous avons mis en place une authentification Basic. Aux vues de ce qui vient d’être dit, vous voyez aisément comment passer à une authentification de type Digest :

7
8
9
10
11
12
13

# Digest HTTP Authentication
http_authentication( :type => :digest, :opaque => "Ma phrase secrète", :realm => "My Capcode test!!!" ) { 
  {
    "greg" => "toto",
    "mu" => "maia"
  }
}

Tout cela c’est très bien me direz vous, mais comment je fais si je veux protéger plusieurs routes avec une même authentification. Prenons l’exemple suivant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

require 'capcode'
 
module Capcode
  class Public < Route '/public'
    def get
      render "You don't need any special authorization here !"
    end
  end
 
  class Private < Route '/private'
    def get
      render "Welcome to the private part of this site !"
    end
  end
 
  class PrivateAgain < Route '/private/again'
    def get
      render "Welcome to the private/again part of this site !"
    end
  end
 
end
 
Capcode.run( )

Avec ce qui a été dit ci-dessus, si nous voulons protéger les parties Private et PrivateAgain, nous devons utiliser deux fois http_authentication. Essayez de le mettre seulement dans Private et vous verrez que vous pouvez accéder à PrivateAgain sans aucun problème. Ce qui est un problème !!!

Heureusement, il y a une solution. En effet, vous pouvez faire une déclaration de demande d’authentification de manière globale. Pour cela j’ai mis en place une méthode Capcode::http_authentication qui ressemble en tout point au helper utilisable dans les contrôleurs, mais prenant un paramètre de plus : :routes. Ainsi, vous pouvez mettre en place la protection souhaitée de la façon suivante :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

require 'capcode'
require 'digest/md5'
 
module Capcode
 
  OPAQUE = Digest::MD5.hexdigest( Time.now.to_s )
  http_authentication( :type => :digest, :opaque => OPAQUE, :realm => "Private parts", :routes => "/private" ) { 
    {
      "greg" => "toto",
      "mu" => "maia"
    }
  }
 
  class Public < Route '/public'
    def get
      render "You don't need any special authorization here !"
    end
  end
 
  class Private < Route '/private'
    def get
      render "Welcome to the private part of this site !"
    end
  end
 
  class PrivateAgain < Route '/private/again'
    def get
      render "Welcome to the private/again part of this site !"
    end
  end
 
end
 
Capcode.run( )

A la ligne 7, nous utilisons la méthode http_authentication pour dire que nous voulons une protection pour toutes les routes ayant pour racine /private. En terme d’expression régulière cela veut dire que si la route match avec /^\/private([\/]{1}.*)?$ alors il faudra s’authentifier pour y accéder.

Notez également que le paramètre :routes peut prendre comme valeur un tableau, ce qui peut grandement nous faciliter la vie si nous voulons utiliser une protection commune pour des routes n’ayant pas la même racine.

Et notre serveur WebDAV alors ? Et bien voici sa nouvelle version :

# file: sample.rb
require 'rubygems'
require 'capcode'
require 'capcode/render/webdav'
 
module Capcode
  # !!! Render file from /Users/greg/Documents/etudes !!!
  class WebDav < Route '/etudes'
    def get
      http_authentication( :type => :digest, :realm => "Greg' WebDAV Server" ) { 
        {
          "greg" => "my super secret password",
          "commercial" => "semaine 23"
        }
      }
      render :webdav => "/Users/greg/Documents"
    end
    def method_missing(id, *a, &b); get; end
  end  
end

Dernière petite chose avant de terminer, sachez que vous pouvez récupérer le login utilisé via request.env['REMOTE_USER'].

¹ bon, j’ai un jour de retard, mais quand même !!!
² Lire également l’article HTTP Authentification de Wikipedia.

Pour régler ce dernier problème, je me suis penché sur WebDAV. Bien entendu, il y a mod_dav sur mon serveur apache. Mais ce n’est pas très souple. Je me suis donc demandé si je ne pouvais pas trouver un serveur WebDAV simple et facile à mettre en place. Et bien c’était sans compter sur Ruby, Rack et surtout rack_dav.

rack_dav permet de monter très facilement un serveur WebDAV. Ce sont les fameuses 4 lignes de code. Par exemple pour partager le contenu de mon répertoire Documents/etudes il suffit de créer le fichier de configuration rackup suivant :

# config.ru
require 'rubygems'; 
require 'rack_dav'; 
use Rack::CommonLogger; 
 
run RackDAV::Handler.new(:root => '/Users/greg/Documents/etudes')

Après avoir lancé rackup, mon dossier est accessible via l’URL http://mon.server.net:9292/.

Le problème vient quand on veut pouvoir partager plusieurs répertoires. Et c’est à ce moment-là que j’ai eu l’idée d’ajouter un moteur de rendu WebDAV dans Capcode. La mise en place est aussi simple que pour les autres moteurs de rendu, et utilise donc la syntaxe render :webdav => "/path/to/root". Ainsi, si je veux mettre en place la même chose que ce que j’ai fait ci-dessus avec rack, je code ceci :

# file: sample.rb
require 'rubygems'
require 'capcode'
require 'capcode/render/webdav'
 
module Capcode
  # !!! Render file from /Users/greg/Documents/etudes !!!
  class WebDav < Route '/etudes'
    def get
      render :webdav => "/Users/greg/Documents"
    end
    def method_missing(id, *a, &b); get; end
  end  
end

Il y a deux choses remarquables ici :

1. Tout d’abord, pour permettre un accès au répertoire /Users/greg/Documents/etudes, j’utilise la route /etudes et le positionne le répertoire racine avec la valeur /Users/greg/Documents. Bien entendu, toutes les combinaisons sont possibles…
2. En plus de la méthode get je définis une méthode method_missing qui appelle la méthode get. Ceci est dû au fait que le protocole WebDAV définit tout un tas de méthodes HTTP, mais qui, dans le cas présent, peuvent toutes être traité comme le GET.

Voilà… Tout cela se trouvera dans la prochaine version de Capcode ou sur github pour les plus pressés.

¹ Il fallait rétablir cette vérité.

Bon, j’ai trouvé la solution, mais elle impose d’avoir toujours son ordinateur portable avec soi. Je me suis créé l’alias suivant :

alias week='ruby -e "require \"date\"; puts Date.commercial( Time.now.year, ARGV[0].to_i|1, 1 ).strftime( \"%d-%m-%Y\")"'

Moi : « Donc, semaine 23 ? »

$ week 23
01-06-2009
$

Lui : « Oui… »
Moi : « Donc à partir du 1er juin… »
Lui : « A ben je sais pas… Semaine 23 quoi ! »