Pre-alphaSpinelMIT

Rails-shaped web apps, compiled to one native binary.

CyberTrain is a Rails-shaped web application framework written natively for Spinel, matz's ahead-of-time Ruby compiler. You keep the vocabulary (resources, before_action, validates, form_with, scaffolds) while cybertrain build compiles controllers, models, views and the framework itself into a single native binary with no Rack, no runtime gems and no Ruby interpreter in the artifact.

Quick start

terminal — any directory, then blog/shell
gem install cybertrain
cybertrain new blog          # installs Spinel the first time (a few 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/

Needs Ruby 3.2+ for the cybertrain command and, in development, the CRuby preview (which also loads fiddle; production needs no Ruby), plus git, make, curl, a C compiler and the SQLite 3 headers: before you start. Run the build with cd dist && ./blog migrate && ./blog and CYBERTRAIN_SECRET_KEY_BASE set.

  • ServerHTTP/1.1, no Rack
  • RuntimeNo gems, no interpreter
  • DatabaseSQLite via Spinel FFI
  • CILinux and macOS

Who it is for, and what it is not

For Rails developers who want a single native binary, and who are comfortable with a young project and a Ruby subset.

  • Not Rails- or Rack-compatible

    No Rack compatibility and no gems at runtime: only Spinel's own spin-index packages that compile under its Ruby subset.

  • Not production-ready

    CyberTrain is pre-alpha. The example blog is exercised by CI on Linux and macOS.

The code you write

Rails vocabulary, with Spinel’s rules written down.

Controllers, models, routes and views read like a Rails app. Where an ahead-of-time compiler forces a difference, it is small, explicit and documented.

  • Routes

    Nested resources blocks take the mapper explicitly: articles.resources :comments.

  • Controllers

    new is written new_action: a method named new would shadow Klass.new(ctx).

  • Views

    In development, templates are read from disk, so editing a view needs no rebuild; cybertrain build embeds them in the binary. They are a closed grammar, not arbitrary Ruby.

  • Models

    class Article declares validations; columns, finders and associations are generated from 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

What works today

The Rails slice you reach for first, written natively for Spinel.

  • Native HTTP server

    Plain-Ruby HTTP/1.1 server with one green thread per connection and typed requests and responses. No Rack layer; put nginx or Caddy in front for TLS.

    TCPServer#accept

  • Routing and controllers

    resources, nested routes, before_action, after_action and rescue_from, generated into plain Ruby at build time. Strong params and flash-then-redirect work as in Rails.

    config/routes.rb

  • Sessions, flash, CSRF

    HMAC-signed cookie sessions, flash messages and CSRF protection are on by default. Forms carry the token automatically; forged posts get a 403.

    _cybertrain_session

  • ERB-flavoured templates

    Views look like Rails ERB with layouts, partials, form_with and link_to. In development they are read from disk, so edits need no rebuild. cybertrain build embeds them.

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

  • SQLite models

    Validations, callbacks and associations derived from foreign keys. Talks to SQLite through Spinel's FFI with a connection pool; every query is bound.

    ffi_func · ffi_lib

  • Migrations and scaffolds

    cybertrain generate scaffold writes migration, model, controller and five views. cybertrain db migrate generates, applies migrations, rewrites db/schema.rb and generates again.

    db/migrate/*.rb

  • Live dev loop

    cybertrain server watches your code and, after a Ruby change, answers from a CRuby preview in under a second while Spinel builds in the background; the compiled binary then takes over the same port. A failed build keeps the preview serving and shows the compiler output.

    X-Cybertrain-Runtime: cruby|spinel

  • Self-testing

    Write tests with Cybertrain::Test and drive the whole app in-process with a cookie-jar client. cybertrain spin test compiles each test and diffs its output.

    test/<name>.rb.expected

Framework and CLI

One name, two parts.

gem install cybertrain installs a command, not the framework. The framework is a Spinel package that your app depends on and compiles in. The gem gives you the cybertrain command, which creates the app, installs Spinel and runs Spinel’s tools for you.

Spinel package

The framework

The library your app is built on.

What is in it

The HTTP server, routing and controllers, sessions and CSRF protection, the template interpreter, SQLite models and migrations, and the code generator behind spin run gen.

How you get it

You don’t install it. Your app’s spin.toml names the release tag of this repository that matches your cybertrain command, and spin lock fetches it into spin’s cache and pins the commit in spin.lock. Nothing is copied into your app.

RubyGem

The cybertrain command

The tool that creates, builds and runs your app.

What is in it

The cybertrain command only: new, generate scaffold, db migrate, server, build, spin, setup and doctor. Neither the framework nor Spinel is in the gem.

How you get it

gem install cybertrain. On first use it builds the pinned Spinel release into ~/.cybertrain, unless that release is already on your PATH.

Both are released from the same tag, so their versions match. How an app moves to a new release is in the Installing guide.

How it works

The metaprogramming happens once, at build time.

Spinel compiles ahead of time and has no eval. So where Rails reaches for method_missing and define_method at runtime, spin run gen writes plain Ruby you can read and commit, and only the views are interpreted.

The CyberTrain pipelinedb/schema.rb, config/routes.rb, app/ and app/views/ feed the build. spin run gen writes plain, committed Ruby into gen/. cybertrain build embeds app/views/ and compiles gen/ and the framework into one native binary, dist/blog, which serves HTTP/1.1 and talks to SQLite through Spinel's FFI. In development app/views/ is read from disk instead, and a return path watches the sources: after a change a CRuby preview answers at once while Spinel builds the binary in the background, and the binary then takes over the port.YOU WRITEBUILD TIME · spinRUN TIMEdb/schema.rbtablesconfig/routes.rbroutesapp/controllers, modelsspin run gen1gen/plain Ruby, committedmodelsroutes · URL helpersview_assignsrun_callbackmigrations · viewsmanifest2cybertrain builddist/blogone native binaryframeworkcontrollers · modelstemplate interpreterembedded viewsHTTP/1.1 serverSQLite via Spinel FFI4app/views/dev: read from diskembedded in dist/blog35dev: watch → CRuby preview → Spineldevelopment only · a failed build keeps the CRuby preview serving The CyberTrain pipelinedb/schema.rb, config/routes.rb, app/ and app/views/ feed the build. spin run gen writes plain, committed Ruby into gen/. cybertrain build embeds app/views/ and compiles gen/ and the framework into one native binary, dist/blog, which serves HTTP/1.1 and talks to SQLite through Spinel's FFI. In development app/views/ is read from disk instead, and a return path watches the sources: after a change a CRuby preview answers at once while Spinel builds the binary in the background, and the binary then takes over the port.YOU WRITEdb/schema.rbtablesconfig/routes.rbroutesapp/controllers, modelsBUILD TIMEspin run gen1gen/plain Ruby, committedmodelsroutes · URL helpersview_assignsrun_callbackmigrations · viewsmanifest2cybertrain buildRUN TIMEdist/blogone native binaryframeworkcontrollers · modelstemplate interpreterembedded viewsHTTP/1.1 serverSQLite via Spinel FFI4app/views/dev: read from diskembedded in dist/blog3dev: watch → CRuby preview → Spinel5development only · a failed buildkeeps the CRuby preview serving
build stepdev only: read from disk / dev loopthe binaryNumbers match the steps below.
  1. Generate at build time

    spin run gen reads db/schema.rb and config/routes.rb, scans app/controllers and app/models, and writes plain, readable Ruby into gen/. cybertrain db migrate, server and build run it for you.

  2. Commit gen/

    It is checked in because spin build and spin test have no hook to generate first. CI re-runs spin run gen and fails on a diff, so stale generated code cannot merge.

  3. Interpret the views

    A tree-walking interpreter renders app/views/**/*.html.erb, read from disk in development and embedded by cybertrain build. Spinel has no eval, so this is a closed grammar, not real Ruby.

  4. Serve with green threads, store in SQLite

    A plain-Ruby HTTP/1.1 server runs one Spinel green thread per connection. Models talk to SQLite through ffi_func/ffi_lib with a 4-connection pool.

  5. Preview, then compile, in development

    cybertrain server serves a Ruby change from a CRuby preview at once, builds the binary in the background and hands it the port when the build finishes (about a minute on examples/blog). A failed build keeps the preview serving, with the compiler output in a banner; cybertrain server --spinel runs the compiled loop alone.

Rails vs CyberTrain

Same vocabulary. Different rules, written down.

An ahead-of-time compiler changes a few habits. These are the ones you meet first.

Differences between Rails and CyberTrain (condensed)
TopicRailsCyberTrain
01Consolerails consoleNo console — Spinel has no eval
02ReloadingEdit code, the running app picks it upRuby changes show at once from a CRuby preview; the compiled binary takes the port when its build finishes (cybertrain server)
03The new actiondef newdef new_action (new would shadow Klass.new(ctx))
04Callbacksbefore_action { do_thing } (implicit self)before_action { |c| c.do_thing } — no instance_exec on a stored block, so callbacks take the controller/record explicitly
05Nested routesresources :posts do resources :comments endresources :posts do |posts| posts.resources :comments end — nested blocks take the mapper explicitly
06SessionsSession holds any marshalled objectSession values are Strings only, HMAC-signed cookie
07DatabaseMany database adaptersSQLite only, via FFI
08Testsminitest / RSpecCybertrain::Test — reflection-based runners can't work ahead-of-time

Not exhaustive.

The full table

Performance

On one core, 2.2 to 8.8 times the requests of Rails.

examples/blog against the same blog written in Rails 8.1, with the same views, routes, models and SQLite schema. Both run in production mode, pinned to the same CPU cores of one machine, under the same load from wrk. A second core helps Rails more: Puma adds a whole process, while CyberTrain’s second worker thread adds 0 to 19%, so on two cores the lead is 1.1 to 4.4 times.

Requests per second with 16 connectionsCyberTrainRails 8.1
  • GET /articlesthe list, 30 articles

    One core

    CyberTrain: 3,218

    Rails: 709

    4.5×vs Rails

    Two cores

    CyberTrain: 3,294

    Rails: 1,453

    2.3×vs Rails

  • GET /articles/1an article with 10 comments and 12 forms

    One core

    CyberTrain: 3,201

    Rails: 364

    8.8×vs Rails

    Two cores

    CyberTrain: 3,211

    Rails: 735

    4.4×vs Rails

  • POST /articles/2/commentsa validated insert and a redirect

    One core

    CyberTrain: 2,081

    Rails: 576

    3.6×vs Rails

    Two cores

    CyberTrain: 2,478

    Rails: 1,089

    2.3×vs Rails

  • GET /style.cssa static file from public/

    One core

    CyberTrain: 22,112

    Rails: 10,144

    2.2×vs Rails

    Two cores

    CyberTrain: 22,735

    Rails: 20,105

    1.1×vs Rails

Memory after the load runs (lower is better)CyberTrainRails 8.1
  • System mallocthe default allocator

    One core

    CyberTrain: 13.9 MB

    Rails: 132.8 MB

    9.6×less

    Two cores

    CyberTrain: 16.0 MB

    Rails: 332.7 MB

    20.8×less

  • jemallocpreloaded into both

    One core

    CyberTrain: 17.4 MB

    Rails: 122.5 MB

    7.0×less

    Two cores

    CyberTrain: 18.3 MB

    Rails: 312.7 MB

    17.1×less

Resident memory (RSS, from /proc) summed over all of the server’s processes, read after all the load runs. Rails runs one Puma process with 3 threads on one core and two workers on two. RSS counts a page that Puma’s workers share once per worker; by PSS, which splits shared pages between processes, Rails on two cores takes 253.9 MB (222.5 MB with jemalloc) against CyberTrain’s 14.1 MB (15.4 MB).

  • Memory under load

    13.9 MB

    Rails: 133 MB, one Puma process with 3 threads.

  • Start to first response

    0.015 s

    Rails: 0.75 s.

  • What the server needs

    4.0 MB

    One binary. Rails: 121 MB of Ruby, 69 gems and the app.

  • The price: a build

    50 s

    to compile the binary with cybertrain build. Rails runs its source as it is.

Medians of three 10-second runs after a warm-up, on a cloud VM with 4 vCPUs: CyberTrain at commit 0d8a942 built with the pinned Spinel release, against Rails 8.1.4 on Ruby 3.4.6 with YJIT and Puma 8.0. The method, every number and how to run it again: docs/benchmark.md.