Pré-alphaSpinelMIT

Des applications web à la Rails, compilées en un seul binaire natif.

CyberTrain est un framework d’applications web à la Rails écrit nativement pour Spinel, le compilateur Ruby AOT de matz. Vous gardez le vocabulaire (resources, before_action, validates, form_with, scaffolds), tandis que cybertrain build compile les contrôleurs, les modèles, les vues et le framework lui-même en un seul binaire natif, sans Rack, sans gems à l’exécution et sans interpréteur Ruby dans l’artefact.

Démarrage rapide

terminal — n’importe quel répertoire, puis blog/shell
gem install cybertrain
cybertrain new blog          # installe Spinel la première fois (quelques minutes)
cd blog
cybertrain g scaffold article title:string body:text
cybertrain db migrate
cybertrain server            # http://127.0.0.1:3000
cybertrain build             # production: dist/blog, dist/public/, dist/storage/, dist/tmp/

Nécessite Ruby 3.2+ pour la commande cybertrain et, en développement, pour l’aperçu CRuby (qui charge aussi fiddle ; la production n’a pas besoin de Ruby), ainsi que git, make, curl, un compilateur C et les en-têtes SQLite 3 : avant de commencer. Lancez le build avec cd dist && ./blog migrate && ./blog, en définissant CYBERTRAIN_SECRET_KEY_BASE.

  • ServeurHTTP/1.1, sans Rack
  • ExécutionNi gems, ni interpréteur
  • Base de donnéesSQLite via la FFI de Spinel
  • CILinux et macOS

Pour qui, et ce que ce n’est pas

Pour les développeurs Rails qui veulent un seul binaire natif et qui s’accommodent d’un projet jeune et d’un sous-ensemble de Ruby.

  • Pas compatible Rails ni Rack

    Aucune compatibilité Rack et aucune gem à l’exécution : uniquement les paquets spin-index propres à Spinel qui compilent avec son sous-ensemble de Ruby.

  • Pas prêt pour la production

    CyberTrain est en pré-alpha. Le blog d’exemple est testé par la CI sous Linux et macOS.

Votre code

Le vocabulaire de Rails, avec les règles de Spinel écrites noir sur blanc.

Contrôleurs, modèles, routes et vues se lisent comme une application Rails. Là où un compilateur AOT impose une différence, elle est minime, explicite et documentée.

  • Routes

    Les blocs resources imbriqués reçoivent le mapper explicitement : articles.resources :comments.

  • Contrôleurs

    new s’écrit new_action : une méthode nommée new masquerait Klass.new(ctx).

  • Vues

    En développement, les templates sont lus depuis le disque, donc modifier une vue ne demande pas de recompilation ; cybertrain build les intègre au binaire. Ils forment une grammaire fermée, pas du Ruby arbitraire.

  • Modèles

    class Article déclare les validations ; les colonnes, les finders et les associations sont générés à partir de db/schema.rb.

config/routes.rbruby
Cybertrain::Routes.draw do
  root "articles#index"

  # A nested block takes the mapper explicitly (Spinel's instance_eval
  # trampoline only rewires `self` for the outermost block): `articles.resources`.
  resources :articles do |articles|
    articles.resources :comments, only: [:create, :destroy]
  end
end
app/controllers/articles_controller.rbruby
# app/controllers/articles_controller.rb (index/show/edit are as plain as
# Rails' own scaffold; update mirrors create)
class ArticlesController < ApplicationController
  before_action :set_article, only: [:show, :edit, :update, :destroy]

  def new_action   # a `new` method would shadow ArticlesController.new
    @article = Article.new
  end

  def create
    @article = Article.new(article_params)
    if @article.save
      flash[:notice] = "Article was successfully created."
      redirect_to article_path(@article), status: :see_other
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def set_article
    @article = Article.find(params[:id])
  end

  def article_params
    params.require(:article).permit(:title, :body)
  end
end
app/views/comments/_comment.html.erberb
<%# locals: (comment:) %>
<div class="comment">
  <p>
    <strong>Commenter:</strong>
    <%= comment.commenter %>
  </p>

  <p>
    <strong>Comment:</strong>
    <%= comment.body %>
  </p>

  <%= button_to "Destroy comment", [@article, comment], method: :delete %>
</div>
app/models/article.rbruby
# app/models/article.rb -- only the first string field gets a default
# presence validation; add anything past that yourself.
class Article
  validates :title, presence: true
  validates :body, presence: true, length: { minimum: 10 }
end

Ce qui fonctionne

La partie de Rails dont vous vous servez en premier, écrite nativement pour Spinel.

  • Serveur HTTP natif

    Serveur HTTP/1.1 en Ruby pur, avec un green thread par connexion et des requêtes et réponses typées. Pas de couche Rack ; placez nginx ou Caddy devant pour le TLS.

    TCPServer#accept

  • Routage et contrôleurs

    resources, routes imbriquées, before_action, after_action et rescue_from, générés en Ruby pur à la compilation. Les strong params et le flash suivi d’une redirection fonctionnent comme dans Rails.

    config/routes.rb

  • Sessions, flash, CSRF

    Les sessions par cookie signé HMAC, les messages flash et la protection CSRF sont activés par défaut. Les formulaires portent le jeton automatiquement ; les POST falsifiés reçoivent une 403.

    _cybertrain_session

  • Templates façon ERB

    Les vues ressemblent à de l’ERB Rails, avec layouts, partiels, form_with et link_to. En développement, elles sont lues depuis le disque, donc les modifications ne demandent pas de recompilation. cybertrain build les intègre.

    app/views/**/*.html.erb

  • Modèles SQLite

    Validations, callbacks et associations déduites des clés étrangères. Dialogue avec SQLite via la FFI de Spinel, avec un pool de connexions ; chaque requête utilise des paramètres liés.

    ffi_func · ffi_lib

  • Migrations et scaffolds

    cybertrain generate scaffold écrit la migration, le modèle, le contrôleur et cinq vues. cybertrain db migrate génère, applique les migrations, réécrit db/schema.rb et génère à nouveau.

    db/migrate/*.rb

  • Boucle de dev à chaud

    cybertrain server surveille votre code et, après une modification Ruby, répond en moins d’une seconde depuis un aperçu CRuby pendant que Spinel compile en arrière-plan ; le binaire compilé reprend ensuite le même port. Un build échoué laisse l’aperçu servir et affiche la sortie du compilateur.

    X-Cybertrain-Runtime: cruby|spinel

  • Tests intégrés

    Écrivez des tests avec Cybertrain::Test et pilotez toute l’application dans le même processus avec un client doté d’une cookie jar. cybertrain spin test compile chaque test et compare (diff) sa sortie.

    test/<name>.rb.expected

Framework et CLI

Un nom, deux parties.

gem install cybertrain installe une commande, pas le framework. Le framework est un paquet Spinel dont votre application dépend et qu’elle compile avec elle. La gem vous fournit la commande cybertrain, qui crée l’application, installe Spinel et lance les outils de Spinel pour vous.

Paquet Spinel

Le framework

La bibliothèque sur laquelle repose votre application.

Contenu

Le serveur HTTP, le routage et les contrôleurs, les sessions et la protection CSRF, l’interpréteur de templates, les modèles SQLite et les migrations, ainsi que le générateur de code derrière spin run gen.

Comment l’obtenir

Vous ne l’installez pas. Le spin.toml de votre application désigne le tag de version de ce dépôt qui correspond à votre commande cybertrain, et spin lock le récupère dans le cache de spin et épingle le commit dans spin.lock. Rien n’est copié dans votre application.

RubyGem

La commande cybertrain

L’outil qui crée, compile et lance votre application.

Contenu

Uniquement la commande cybertrain : new, generate scaffold, db migrate, server, build, spin, setup et doctor. Ni le framework ni Spinel ne sont dans la gem.

Comment l’obtenir

gem install cybertrain. À la première utilisation, elle compile la version épinglée de Spinel dans ~/.cybertrain, sauf si cette version est déjà dans votre PATH.

Les deux sont publiés à partir du même tag, leurs versions correspondent donc. Comment une application passe à une nouvelle version est expliqué dans le guide d’installation.

Fonctionnement

La métaprogrammation a lieu une seule fois, à la compilation.

Spinel compile à l’avance et n’a pas d’eval. Là où Rails recourt à method_missing et à define_method à l’exécution, spin run gen écrit donc du Ruby pur que vous pouvez lire et commiter, et seules les vues sont interprétées.

Le pipeline CyberTraindb/schema.rb, config/routes.rb, app/ et app/views/ alimentent le build. spin run gen écrit du Ruby pur, versionné, dans gen/. cybertrain build intègre app/views/ et compile gen/ et le framework en un seul binaire natif, dist/blog, qui sert du HTTP/1.1 et dialogue avec SQLite via la FFI de Spinel. En développement, app/views/ est plutôt lu depuis le disque, et un chemin de retour surveille les sources : après un changement, un aperçu CRuby répond tout de suite pendant que Spinel compile le binaire en arrière-plan, puis le binaire reprend le port.YOU WRITEBUILD TIME · spinRUN TIMEdb/schema.rbtablesconfig/routes.rbroutesapp/controllers, modelsspin run gen1gen/Ruby pur, versionnémodelsroutes · helpers URLview_assignsrun_callbackmigrations · vuesmanifest2cybertrain builddist/blogun binaire natifframeworkcontrollers · modelstemplate interpretervues intégréesHTTP/1.1 serverSQLite via Spinel FFI4app/views/dev : lu sur disqueintégré à dist/blog35dev: watch → CRuby preview → Spinelen dev uniquement · build échoué garde l’aperçu CRuby actif Le pipeline CyberTraindb/schema.rb, config/routes.rb, app/ et app/views/ alimentent le build. spin run gen écrit du Ruby pur, versionné, dans gen/. cybertrain build intègre app/views/ et compile gen/ et le framework en un seul binaire natif, dist/blog, qui sert du HTTP/1.1 et dialogue avec SQLite via la FFI de Spinel. En développement, app/views/ est plutôt lu depuis le disque, et un chemin de retour surveille les sources : après un changement, un aperçu CRuby répond tout de suite pendant que Spinel compile le binaire en arrière-plan, puis le binaire reprend le port.YOU WRITEdb/schema.rbtablesconfig/routes.rbroutesapp/controllers, modelsBUILD TIMEspin run gen1gen/Ruby pur, versionnémodelsroutes · helpers URLview_assignsrun_callbackmigrations · vuesmanifest2cybertrain buildRUN TIMEdist/blogun binaire natifframeworkcontrollers · modelstemplate interpretervues intégréesHTTP/1.1 serverSQLite via Spinel FFI4app/views/dev : lu sur disqueintégré à dist/blog3dev: watch → CRuby preview → Spinel5en dev uniquement · build échouégarde l’aperçu CRuby actif
étape de builddev uniquement : lecture depuis le disque / boucle de devle binaireLes numéros correspondent aux étapes ci-dessous.
  1. Générer à la compilation

    spin run gen lit db/schema.rb et config/routes.rb, analyse app/controllers et app/models, et écrit du Ruby pur et lisible dans gen/. cybertrain db migrate, server et build le lancent pour vous.

  2. Commiter gen/

    Il est versionné car spin build et spin test n’ont pas de hook pour générer d’abord. La CI relance spin run gen et échoue en cas de diff : du code généré périmé ne peut donc pas être fusionné.

  3. Interpréter les vues

    Un interpréteur d’arbre (tree-walking) rend les app/views/**/*.html.erb, lus depuis le disque en développement et intégrés par cybertrain build. Spinel n’a pas d’eval, il s’agit donc d’une grammaire fermée, pas de vrai Ruby.

  4. Servir avec des green threads, stocker dans SQLite

    Un serveur HTTP/1.1 en Ruby pur exécute un green thread Spinel par connexion. Les modèles dialoguent avec SQLite via ffi_func/ffi_lib, avec un pool de 4 connexions.

  5. Aperçu, puis compilation, en développement

    cybertrain server sert tout de suite une modification Ruby depuis un aperçu CRuby, compile le binaire en arrière-plan et lui passe le port quand la compilation se termine (environ une minute sur examples/blog). Un build échoué laisse l’aperçu servir, avec la sortie du compilateur en bannière ; cybertrain server --spinel lance la boucle compilée seule.

Rails vs CyberTrain

Même vocabulaire. Des règles différentes, écrites noir sur blanc.

Un compilateur AOT change quelques habitudes. Voici celles que vous rencontrerez en premier.

Différences entre Rails et CyberTrain (version condensée)
SujetRailsCyberTrain
01Consolerails consolePas de console — Spinel n’a pas d’eval
02RechargementModifiez le code, l’application en cours d’exécution le prend en compteLes modifications Ruby apparaissent tout de suite grâce à un aperçu CRuby ; le binaire compilé reprend le port quand sa compilation se termine (cybertrain server)
03L’action newdef newdef new_action (new masquerait Klass.new(ctx))
04Callbacksbefore_action { do_thing } (self implicite)before_action { |c| c.do_thing } — pas d’instance_exec sur un bloc stocké, donc les callbacks reçoivent explicitement le contrôleur/l’enregistrement
05Routes imbriquéesresources :posts do resources :comments endresources :posts do |posts| posts.resources :comments end — les blocs imbriqués reçoivent le mapper explicitement
06SessionsLa session contient n’importe quel objet sérialisé (marshal)Valeurs de session de type String uniquement, cookie signé HMAC
07Base de donnéesDe nombreux adaptateurs de base de donnéesSQLite uniquement, via FFI
08Testsminitest / RSpecCybertrain::Test — les runners fondés sur la réflexion ne peuvent pas fonctionner avec une compilation AOT

Liste non exhaustive.

Le tableau complet

Performances

Sur un cœur, 2,2 à 8,8 fois plus de requêtes que Rails.

examples/blog face au même blog écrit en Rails 8.1 : mêmes vues, routes, modèles et schéma SQLite. Les deux tournent en mode production, épinglés sur les mêmes cœurs d’une même machine, sous la même charge envoyée par wrk. Un second cœur profite surtout à Rails : Puma ajoute tout un processus, alors que le second thread de travail de CyberTrain n’ajoute que 0 à 19 %, si bien que sur deux cœurs l’écart est de 1,1 à 4,4 fois.

Requêtes par seconde avec 16 connexionsCyberTrainRails 8.1
  • GET /articlesla liste, 30 articles

    Un cœur

    CyberTrain: 3 218

    Rails: 709

    4,5×face à Rails

    Deux cœurs

    CyberTrain: 3 294

    Rails: 1 453

    2,3×face à Rails

  • GET /articles/1un article avec 10 commentaires et 12 formulaires

    Un cœur

    CyberTrain: 3 201

    Rails: 364

    8,8×face à Rails

    Deux cœurs

    CyberTrain: 3 211

    Rails: 735

    4,4×face à Rails

  • POST /articles/2/commentsune insertion validée et une redirection

    Un cœur

    CyberTrain: 2 081

    Rails: 576

    3,6×face à Rails

    Deux cœurs

    CyberTrain: 2 478

    Rails: 1 089

    2,3×face à Rails

  • GET /style.cssun fichier statique de public/

    Un cœur

    CyberTrain: 22 112

    Rails: 10 144

    2,2×face à Rails

    Deux cœurs

    CyberTrain: 22 735

    Rails: 20 105

    1,1×face à Rails

Mémoire après les passes de charge (moins, c’est mieux)CyberTrainRails 8.1
  • malloc du systèmel’allocateur par défaut

    Un cœur

    CyberTrain: 13,9 Mo

    Rails: 132,8 Mo

    9,6×de moins

    Deux cœurs

    CyberTrain: 16,0 Mo

    Rails: 332,7 Mo

    20,8×de moins

  • jemallocpréchargé dans les deux

    Un cœur

    CyberTrain: 17,4 Mo

    Rails: 122,5 Mo

    7,0×de moins

    Deux cœurs

    CyberTrain: 18,3 Mo

    Rails: 312,7 Mo

    17,1×de moins

Mémoire résidente (RSS, lue dans /proc) additionnée sur tous les processus du serveur, relevée après toutes les passes de charge. Rails tourne en un processus Puma à 3 threads sur un cœur et en deux workers sur deux. Le RSS compte une page partagée entre les workers de Puma une fois par worker ; en PSS, qui répartit les pages partagées entre les processus, Rails sur deux cœurs occupe 253,9 Mo (222,5 Mo avec jemalloc) contre 14,1 Mo (15,4 Mo) pour CyberTrain.

  • Mémoire sous charge

    13,9 Mo

    Rails : 133 Mo, un processus Puma à 3 threads.

  • Du lancement à la première réponse

    0,015 s

    Rails : 0,75 s.

  • Ce qu’il faut sur le serveur

    4,0 Mo

    Un seul binaire. Rails : 121 Mo de Ruby, de 69 gems et de l’application.

  • Le prix : une compilation

    50 s

    pour compiler le binaire avec cybertrain build. Rails exécute ses sources telles quelles.

Médianes de trois mesures de 10 secondes après un échauffement, sur une VM cloud à 4 vCPU : CyberTrain au commit 0d8a942 compilé par la version épinglée de Spinel, face à Rails 8.1.4 sur Ruby 3.4.6 avec YJIT et Puma 8.0. La méthode, tous les chiffres et comment relancer la mesure : docs/benchmark.md.