Spinel 包
框架
你的应用所基于的库。
包含什么
HTTP 服务器、路由和控制器、会话与 CSRF 防护、模板解释器、SQLite 模型和迁移,以及 spin run gen 背后的代码生成器。
如何获取
你不需要安装它。你的应用的 spin.toml 指定本仓库与你的 cybertrain 命令相对应的发布标签,spin lock 会把它拉取到 spin 的缓存中,并在 spin.lock 中锁定提交。不会有任何内容被复制到你的应用中。
预 AlphaSpinelMIT
Rails 风格的 Web 应用,编译为单个原生二进制文件。
CyberTrain 是一个 Rails 风格的 Web 应用框架,专为 matz 开发的 Ruby AOT 编译器 Spinel 原生编写。你沿用熟悉的词汇(resources、before_action、validates、form_with、脚手架),而 cybertrain build 会把控制器、模型、视图以及框架本身编译成单个原生二进制文件,产物中没有 Rack、没有运行时 gem,也没有 Ruby 解释器。
快速上手
gem install cybertrain
cybertrain new blog # 首次运行时安装 Spinel(需要几分钟)
cd blog
cybertrain g scaffold article title:string body:text
cybertrain db migrate
cybertrain server # http://127.0.0.1:3000
cybertrain build # 生产环境:dist/blog、dist/public/、dist/storage/、dist/tmp/
cybertrain 命令和开发时的 CRuby 预览需要 Ruby 3.2+(预览还会加载 fiddle;生产环境不需要 Ruby),此外还需要 git、make、curl、C 编译器和 SQLite 3 头文件:参见开始之前。设置好 CYBERTRAIN_SECRET_KEY_BASE 后,用 cd dist && ./blog migrate && ./blog 运行构建产物。
面向想要单个原生二进制文件、并且能接受一个年轻项目和 Ruby 子集的 Rails 开发者。
没有 Rack 兼容性,运行时也没有 gem:只能使用 Spinel 自己的、能在其 Ruby 子集下编译的 spin-index 包。
CyberTrain 处于预 Alpha 阶段。示例博客由 CI 在 Linux 和 macOS 上运行测试。
你编写的代码
控制器、模型、路由和视图读起来就像一个 Rails 应用。凡是 AOT 编译器迫使其有所不同的地方,差异都很小、很明确,并且有文档说明。
路由
嵌套的 resources 块需要显式接收 mapper:articles.resources :comments。
控制器
new 要写成 new_action:名为 new 的方法会遮蔽 Klass.new(ctx)。
视图
开发时模板从磁盘读取,所以修改视图无需重新构建;cybertrain build 会把它们嵌入二进制文件。模板是一套封闭的语法,而不是任意 Ruby。
模型
class Article 声明验证;列、查找方法和关联都根据 db/schema.rb 生成。
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.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
<%# 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.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
现已可用
纯 Ruby 编写的 HTTP/1.1 服务器,每个连接一个绿色线程,请求和响应都带有类型。没有 Rack 层;需要 TLS 时在前面放 nginx 或 Caddy。
TCPServer#accept
resources、嵌套路由、before_action、after_action 和 rescue_from,在构建时生成为纯 Ruby。强参数和“先 flash 再重定向”的用法与 Rails 相同。
config/routes.rb
HMAC 签名的 cookie 会话、flash 消息和 CSRF 防护默认开启。表单会自动携带令牌;伪造的 POST 请求会得到 403。
_cybertrain_session
视图看起来就像 Rails 的 ERB,支持布局、局部视图、form_with 和 link_to。开发时从磁盘读取,所以修改后无需重新构建。cybertrain build 会把它们嵌入。
app/views/**/*.html.erb
验证、回调,以及由外键推导出的关联。通过 Spinel 的 FFI 和连接池访问 SQLite;所有查询都使用参数绑定。
ffi_func · ffi_lib
cybertrain generate scaffold 会写出迁移、模型、控制器和五个视图。cybertrain db migrate 先生成代码,再执行迁移、重写 db/schema.rb,然后再次生成。
db/migrate/*.rb
cybertrain server 监视你的代码:Ruby 改动后,CRuby 预览在一秒内响应,同时 Spinel 在后台构建;构建完成后,编译好的二进制文件接管同一端口。构建失败时预览继续提供服务,并显示编译器输出。
X-Cybertrain-Runtime: cruby|spinel
用 Cybertrain::Test 编写测试,并通过带 cookie jar 的客户端在进程内驱动整个应用。cybertrain spin test 会编译每个测试并比对其输出。
test/<name>.rb.expected
框架与 CLI
gem install cybertrain 安装的是一个命令,而不是框架。框架是一个 Spinel 包,你的应用依赖它并把它编译进来。这个 gem 提供 cybertrain 命令,它会替你创建应用、安装 Spinel 并运行 Spinel 的工具。
Spinel 包
你的应用所基于的库。
包含什么
HTTP 服务器、路由和控制器、会话与 CSRF 防护、模板解释器、SQLite 模型和迁移,以及 spin run gen 背后的代码生成器。
如何获取
你不需要安装它。你的应用的 spin.toml 指定本仓库与你的 cybertrain 命令相对应的发布标签,spin lock 会把它拉取到 spin 的缓存中,并在 spin.lock 中锁定提交。不会有任何内容被复制到你的应用中。
RubyGem
cybertrain 命令用来创建、构建和运行你的应用的工具。
包含什么
只有 cybertrain 命令:new、generate scaffold、db migrate、server、build、spin、setup 和 doctor。框架和 Spinel 都不在这个 gem 里。
如何获取
gem install cybertrain。首次使用时,它会把锁定的 Spinel 版本构建到 ~/.cybertrain 中,除非你的 PATH 上已经有该版本。
两者从同一个标签发布,因此版本一致。安装指南中有应用如何迁移到新版本的说明。
工作原理
Spinel 进行 AOT 编译,没有 eval。因此,凡是 Rails 在运行时借助 method_missing 和 define_method 的地方,spin run gen 都会写出你可以阅读和提交的纯 Ruby 代码,只有视图是解释执行的。
spin run gen 读取 db/schema.rb 和 config/routes.rb,扫描 app/controllers 和 app/models,并把可读的纯 Ruby 代码写入 gen/。cybertrain db migrate、server 和 build 会替你运行它。
gen/它要提交进仓库,因为 spin build 和 spin test 没有可以先执行生成的钩子。CI 会重新运行 spin run gen,一旦有差异就失败,因此过时的生成代码无法合并。
一个遍历树的解释器渲染 app/views/**/*.html.erb:开发时从磁盘读取,由 cybertrain build 嵌入二进制文件。Spinel 没有 eval,所以这是一套封闭的语法,而不是真正的 Ruby。
纯 Ruby 编写的 HTTP/1.1 服务器为每个连接运行一个 Spinel 绿色线程。模型通过 ffi_func/ffi_lib 访问 SQLite,使用 4 个连接的连接池。
cybertrain server 在 Ruby 改动后立即用 CRuby 预览提供服务,在后台构建二进制文件,构建完成后把端口交给它(在 examples/blog 上约一分钟)。构建失败时预览继续提供服务,并以横幅显示编译器输出;cybertrain server --spinel 只运行编译版的循环。
Rails 与 CyberTrain
AOT 编译器会改变一些习惯。下面是你最先会遇到的几条。
| 主题 | Rails | CyberTrain |
|---|---|---|
| 01控制台 | rails console | 没有控制台——Spinel 没有 eval |
| 02重新加载 | 修改代码,正在运行的应用会自动加载 | Ruby 的改动立即通过 CRuby 预览生效;构建完成后,编译好的二进制文件接管端口(cybertrain server) |
| 03new 动作 | def new | def new_action(new 会遮蔽 Klass.new(ctx)) |
| 04回调 | before_action { do_thing }(隐式 self) | before_action { |c| c.do_thing }——无法对存储的块使用 instance_exec,因此回调需要显式接收控制器/记录 |
| 05嵌套路由 | resources :posts do resources :comments end | resources :posts do |posts| posts.resources :comments end——嵌套块需要显式接收 mapper |
| 06会话 | 会话可以保存任何经 marshal 序列化的对象 | 会话值只能是 String,使用 HMAC 签名的 cookie |
| 07数据库 | 多种数据库适配器 | 仅支持 SQLite,通过 FFI 访问 |
| 08测试 | minitest / RSpec | Cybertrain::Test——基于反射的测试运行器无法在 AOT 编译下工作 |
此表并不完整。
完整表格性能
对比 examples/blog 与用 Rails 8.1 编写的同一个博客:视图、路由、模型和 SQLite 模式都相同。两者都以生产模式运行,固定在同一台机器的相同 CPU 核心上,由 wrk 施加相同的负载。第二个核心对 Rails 的帮助更大:Puma 会多开一个完整的进程,而 CyberTrain 的第二个工作线程只带来 0% 到 19% 的提升,因此在两个核心上差距为 1.1 到 4.4 倍。
GET /articles列表,30 篇文章
一个核心
4.5×对比 Rails
两个核心
2.3×对比 Rails
GET /articles/1一篇带 10 条评论和 12 个表单的文章
一个核心
8.8×对比 Rails
两个核心
4.4×对比 Rails
POST /articles/2/comments一次带验证的插入和一次重定向
一个核心
3.6×对比 Rails
两个核心
2.3×对比 Rails
GET /style.csspublic/ 中的静态文件
一个核心
2.2×对比 Rails
两个核心
1.1×对比 Rails
系统 malloc默认分配器
一个核心
9.6×更少
两个核心
20.8×更少
jemalloc两者都预加载
一个核心
7.0×更少
两个核心
17.1×更少
服务器所有进程的常驻内存(从 /proc 读取的 RSS)之和,在全部负载运行结束后读取。Rails 在一个核心上运行一个 3 线程的 Puma 进程,在两个核心上运行两个工作进程。RSS 会把 Puma 工作进程共享的页面按每个进程各算一次;按在进程间分摊共享页面的 PSS 计算,两个核心上的 Rails 占用 253.9 MB(使用 jemalloc 时为 222.5 MB),而 CyberTrain 为 14.1 MB(15.4 MB)。
负载下的内存
13.9 MB
Rails:133 MB(一个 Puma 进程,3 个线程)。
从启动到首个响应
0.015 秒
Rails:0.75 秒。
服务器上需要的东西
4.0 MB
一个二进制文件。Rails:Ruby、69 个 gem 和应用,共 121 MB。
代价:一次构建
50 秒
用 cybertrain build 编译二进制文件所需的时间。Rails 直接运行源代码。
预热之后三次 10 秒测量的中位数,环境为一台 4 vCPU 的云虚拟机:用锁定的 Spinel 版本构建的 CyberTrain(提交 0d8a942),对比运行在 Ruby 3.4.6(启用 YJIT)和 Puma 8.0 上的 Rails 8.1.4。测量方法、全部数字以及如何重新测量:docs/benchmark.md。