ylt (袁乐天)

写了一个 Libra 的客户端库

ylt — Sat, 19 Oct 2019 10:28:26 +0800

Libra 是 facebook 推出的一种数字货币，和实际的法币挂钩，在我看来是‘真实’的货币，应该可以算是 M0。最近几个月尝试给 Libra 项目写一个 ruby 的客户端，最终形成了两个开源项目'casoer-ruby'和'libra_client_ruby'：

casoer-ruby : LCS 的 ruby 实现

A Ruby implementation of the LCS(Libra Canonical Serialization)

LCS(Libra Canonical Serialization) 是 Libra 中采用的规范序列化协议。它可确保内存里的数据结构在序列化的时候保证字节一致性。它适用于双方想要有效比较他们独立维护的数据结构。在共识协议中，独立验证者需要就他们独立计算的状态达成一致。共识双方比较的是序列化数据的加密散列。要实现这一点，在计算时，相同数据结构的序列化必须相同。而独立验证器可能由不同的语言编写，有不同的实现代码，但是都遵循同一个规范。

libra_client_ruby : 访问 Libra 网络的 Ruby 语言 API

Cient APIs for the Libra network

Libra 网络采用的是 protobuf+grpc 的接口协议， 'libra_client_ruby'主要是对该协议的封装。安装方式很简单，标准的 gem 命令：

gem install libra_client

要访问 Libra 网络，参考下面的代码：

require 'libra_client'
client = Libra::Client.new(:testnet)
state = client.get_account_state("000000000000000000000000000000000000000000000000000000000a550c18")
state.balance           #the balance of the account
state.sequence_number   #the sequence_number of the account

在写这个库的过程中，碰到了一个难题。Ruby 目前不支持 SHA3 系列散列算法，包括 SHA3_224, SHA3_256, SHA3_384 and SHA3_512。但是 Libra 中使用的 Hash 算法是 SHA3_256。我尝试自己实现了 Openssl 中 SHA3 系列函数的 Ruby 移植，但是pull request没有通过，最后放弃了。

Libra 客户端库的 Python 实现

由于 python 和 ruby 语法类似，且支持 SHA3_256，所以我尝试用 python 重写了一遍上面的两个库。而且 python 的版本支持完整的客户端功能，比如交易和钱包。

A Python implementation of the LCS(Libra Canonical Serialization)

Python Language APIs for the Libra network

等 ruby 支持了 SHA3, 也许考虑升级一些 ruby 的客户端。

开源一个超酷的 Restful API 自动生成器：Kaola

ylt — Fri, 21 Jul 2017 00:53:20 +0800

项目的地址是： https://github.com/yuanxinyu/kaola

0. 什么是 Kaola

Kaola（考拉，英文 koala）是一个全自动的 restful api 代码自动生成系统。给定一个数据库，只需要配置好数据库连接，koala 可以通过扫描数据库自动生成全套的 restful api 的后端代码。通过预先约定好的接口调用规范，前端就可以直接开发应用系统了。

1. 为什么开发 Kaola

类似 koala 的代码生成系统之前也有很多，比如 rails 自带的 scaffold 功能，以及更完善的 Active Admin／Rails Admin 等。但是这些系统都有两点不符合要求：

这些系统都是一套完整的系统，从后端到页面都一次性生成。实际的情况是，后端的接口比较通用，而界面和操作流程往往需要深度的定制。修改这些系统自动生成的页面是很困难的。
这些系统往往都是只支持单表 CRUD 操作，对多表之间的关联操作支持不够。

所以我开发了这套 koala 系统，它的主要特点是：

只提供后端的 restful api 接口，前端的代码还是需要每个应用自己编写，采用前后端分离架构；
接口不仅支持常规的单表 CRUD 操作，还自动支持多表关联（一对多、多对多、自引用的树形结构），支持复杂的查询（分页、排序、计数、索引）、支持批量操作、以及拥有一套透明高效的缓存体系。

当然，还有一点很重要的，就是定义了一套 restful 的基于约定的接口协议。基于这套约定的协议，前端程序员不需要后端提供繁琐的不一致接口文档，可以轻松上手开始使用这套接口。

2. Kaola 的接口协议约定

Kaola 生成的 Api 接口是基于 http 的 web 接口，URL 的命名基本沿用 rails 框架的命名约定，其中的表名都是复数形式。基本的 CRUD 接口的约定如下：

操作	HTTP Method	URI
获取列表数据	GET	/表名 (.:format)
添加新数据	POST	/表名 (.:format)
修改已有数据	PUT	/表名/:id(.:format)
查看已有数据	GET	/表名/:id(.:format)
删除已有数据	DELETE	/表名/:id(.:format)

这只是对单表资源的 CRUD 操作，koala 针对下列情况也定义了一套的 Restful 规范：

查询／分页／排序的支持。标准 Restful 接口只有一个列表的接口，对查询相关的功能没有约定，koala 自行扩展了一套约定。
批量操作的支持。Restful 接口默认只支持单个资源的操作，而实际的业务场景中经常需要有批量操作的需求，比如商品的批量上架、数据的批量删除等。
有关联的数据表的支持。Restful 只支持单个资源的 CRUD，而实际业务中经常有主子表的级联保存，关联表的查询等。

查询的约定

Kaola 的查询参数一一对应到数据库中的字段，格式是通过把 json 格式的查询参数扁平化得来的。比如下面的查询条件，

{
    "s" : {
        gender : 'm',
        "like" : {
            name : 'b'
        }
    },
    "order" : "id asc"
}

它的含义是查找所有 gender 等于'm'并且 name 包含'b'的记录，按'id asc'排序，扁平化以后就是：

s[gender]=m&s[like[name]]=b&order=id asc

如果表的名字是‘users’，那么请求‘users.json?s[gender]=m&s[like[name]]=b&order=id+asc’就可以得到所有符合条件的 json 格式的数据。

针对查询／分页／排序／批量操作／关联表操作／导入导出等的具体的约定（前端开发者需要细看）可以参考：

kaola api 协议规范；

3. 开始使用 Kaola

Kaola 是基于 ruby on rails 开发的，主要在 Mac 和 Linux 操作系统下完成开发，数据库使用的是 mysql。如果你的操作系统是 windows，或者数据库不是 mysql，大体上是兼容的，但可能会碰到问题。

安装 ruby2.2 以上版本，如何安装可参考这个链接。安装完成 ruby 以后，在命令行运行”gem install bundle”以安装 bundle；
下载 koala 的代码，在项目根目录运行“bundle install”安装依赖的第三方库；
配置数据库连接，具体参考数据库配置；
在项目的根目录运行“./autogen.sh”，自动生成所有的后端 api 代码；
启动 api 服务器，在开发环境下就是运行“rails server”

然后打开浏览器访问这个链接就可以看到生成的所有接口了。在开发环境下，koala 除了 api 接口，也提供完整的 CRUD 的 html 页面（其实就是 rails 默认的 scaffold 生成的页面）。在发布环境下，只有接口调用可以访问，基本就是以".json"结尾的 url 访问。

4. 实现原理

扫描数据库实现所有单表的 CRUD 功能接口，这个不难实现。比较难的是怎么处理数据关联关系。数据关联关系主要有三种：一对多，一对一，多对多。Kaola 在实现关联关系的时候，分两个阶段实现的。

识别一对多关系

第一个阶段，在 2016 年项目最初开发的时候，只支持一对多关系。一对一关系是一对多关系的特例，而多对多关系则可以表示为两个一对多关系，所以只支持一对多关系也不算严重的缺陷。

那么如何自动发现数据库所有的一对多关系呢，主要通过三种方法：

通过数据库的外键。如果 A 表有一个外键指向 B 表，那么 B 表和 A 表就是一对多关系。
通过命名约定。外键的命名约定采用 rails 默认的约定，外键的名字都是“表名单数_id”。同时对 rails 的约定有扩展，如果一张表里有多个关联到另外一张表的外键，命名规则是“前缀_表名单数_id”。所有符合命名约定的表，即使没有设置数据库层的外键，也自动建立一对多关系。

3.通过配置文件。有些遗留的数据库即没有配置外键，也不符合命名约定，那么在配置文件 custom_fk.txt 文件中配置好外键关系也可以。

关联关系是双向的，对于两个表 table1s 和 table2s，如果 table1 有一个字段 table2_id，那么 table1 是多方，table2 是一方，用 rails 来描述就是：

Table1 belongs_to table2
Table2 has_many  table1s

识别多对多关系

第二个阶段是 2017 年，kaola 开发完成接近一年的时候，有个项目组提出要多对多关系的支持，在压力下想明白了多对多关系。首先，rails 支持两种多对多关系：直接式的“has_and_belongs_to_many”和间接式的“has_many through”, 对应的例子见下图：

Rails 已经不建议使用直接式的多对多关系参考，Kaola 也不支持这种方式。下面就是自动发现多对多关联的最关键一步：所有包含两个及以上外键（也包括命名约定／配置文件定义的外键）的表自动形成多对多关系。一张表有 2/3/4 个外键，分别会定义 1/2/6 个多对多关系，也就是给定 n 个外键，生产组合 C(2,n) 个多对多关系。

除了常规的三种关系，还有一种特殊的自引用关系：树形结构。树形结构最常见的例子有组织结构、产品类别等。为了存储树形结构，要求给定的表有一个指向自己的外键。外键值为空的节点是树的根节点。树形结构在 kaola 中被定义为一个指向自己的一对多关系。

关系的增删改

识别了这些常见的数据关联关系后，接下来的任务是如何支持对这些关系的增删改查操作。目前对关系数据的增删改还只支持一对多关系，不支持多对多关系。由于 kaola 采用 json 格式提交数据，所以新增和修改有关系的数据是比较容易的，json 格式很容易支持用嵌套结构来表达一对多关系。比如单个新增的话，提交的是一个 hash 对象

{
    "表名单数": {id:id, key:value,...}
}

那么对于一次性提交主子表的数据，格式就是

{
    "主表单数": {id:id, key:value,...},
    "子表复数": [
        {id:id, key:value,...},
        {id:id, key:value,...}
    ],
    其它子表...
}

关系的查询

下一步是如何定义和实现关联关系的查询。Kaola 使用了面向对象语言的“.”操作符来表达主子表的关系，从而可以达到比 sql 语句更简单自然的查询表达式。比如有两张表：公司表 companies 和仓库表 warehouses，一个公司可以有多个仓库，那么下面的查询

warehouses.json?s[company.name]='公司 A'

表示查询所有的 name 为‘公司 A’的公司所有的仓库。对应的 Sql 查询是：

select * from warehouses join companies on warehouses.company_id = companies.id where companies.name='公司 A'

关联表的查询支持所有单表查询的功能，包括等于／Like／日期／数值范围／枚举查询。此外，针对一对多关系，还支持两种特殊的查询：Exists 查询（给定主表是否有子表数据）和树形结构查询（给定数据节点的所有深层嵌套子节点）。

具体的技术实现细节可以参考：

kaola 技术实现；

5. 案例

Kaola 主要的使用场合是内部 IT 系统的后端，比如各类管理后台、各类信息管理系统（CRM／SCM／ERP／HIS）等。

单语言案例：供应链系统

Kaola 最初的场景是用在一个供应链系统中。这个系统有几百张表，表间的关联复杂。应用 Kaola 后，整个后端代码量大大减少，所有增删改查的 api 都是自动生成的。最后只有三个文件，几百行代码是需要为供应链的逻辑定制的。这三个文件分别处理各类订单流水号生成逻辑、库存计算逻辑、订单流转逻辑。这些逻辑都是通过 rails 的数据库钩子实现的，不修改自动生成的代码，所以维护也很方便。比如下面就是序列号生成逻辑／订单流转逻辑的模版代码。

class ActiveRecord::Base
  before_validation :gen_seq

  def gen_seq
    #序列号生成逻辑
  end
end

class ActiveRecord::Base
  before_update :order_process

  def order_process
    #订单流转逻辑
  end
end

如果你的团队后端有 ruby 程序员，这是推荐使用 kaola 的方式，增删改查的 api 用 kaola 自动生成，其它的功能通过修改 kaola 的代码实现。

混合语言后端案例

如果你的团队后端没有 ruby 程序员，也可以使用 kaola 来帮助减少后端的开发工作量。通过采用前后端分离架构，前端开发其实不关心后端的 api 是用什么语言实现的。

我们在一个健康干预系统项目中采用了混合语言后端的案例。这个项目组都是 java 后端程序员，通过 kaola 来帮助 java 程序员完成增删改查的 api，而健康干预计划／健康报告生成等功能则是独立部署的 java 后端实现的。

6. 杂项

发布

由于 kaola 提供 api 接口能力太广泛，不能直接暴露在网络上。所以在发布的时候，需要部署在一个 api 网关后面，比如 Netflix/zuul 这样的网关。

License

Kaola 采用 MIT License， https://opensource.org/licenses/MIT

为何取名 Kaola

俗话说，懒惰是程序员的美德，能够让计算机自动完成的事情，就不要重复劳动了。取名 Kaola 是希望这套系统让程序员可以像考拉一样悠闲，同时 restful 也有宁静的含义，和考拉的形象比较匹配。

去年的技术分享

2016 年在高可用架构社区做的一次技术分享：

一次无后端的供应链系统开发实践 (上篇)：前后端分离的 Restful 接口设计

ylt — Wed, 07 Dec 2016 11:47:23 +0800

本人在去年底加入了一家医疗保险行业的创业公司‘亿保健康’，公司的技术是基于 Java 体系的。而这次的分享是今年做的一个新的供应链项目。当时项目组缺后端 java 程序员，所以我用 ruby 写了一个自动化的后端。本文分享供应链项目采用的后端自动化技术，该技术极大提升了项目的开发效率。

1. 缘起

我们在 2016 年初上线了一个网上药房：老白网 laobai.com。半年多的时间，老白网的官网销售额在全国自营的网上药房里已经排名前 10 了。电商的后端需要有一套供应链管理系统，但是由于药品的特殊性，药品采购／仓储／物流等需要符合 GSP 规范，导致我们目前外购并同时使用两套供应链系统，一套通用版满足基本的功能需求，一套主要是药品的 GSP 审核的需要，两个系统之间还需要数据交换。此外，这些外购的系统也无法满足我们自己的一些定制化开发的需求。所以就迫切需要自己开发一个满足 GSP 规范的药品行业供应链系统。

外购的第三方的供应链系统有 1000 多张表，功能上的复杂度主要在数据表多且有关联，对性能／并发上到是没有太多的要求。因为可以参考第三方的数据库结构设计，也可以参考第三方的界面设计，所以数据库／前端都没有太多的不确定性。当时这个项目的团队情况是有一个靠谱的 DBA，有几个前端开发，但是缺少后端程序员。功能很多，需要开发的人力缺口很大，正是在这种情况下催生了本文提到的技术方案。方案的主要考虑是：

数据库设计完成后，前端要求可以直接开始开发，不能等后端接口。
后端的开发工作量要尽可能少，多用代码生成技术，因为没有专职的后端程序员。

2. REST 的优点与不完备性

关于前后端之间的接口规范，主要有三种风格：RPC vs REST vs GraphQL。 RPC 风格的接口规范是最传统的，但是不太合适基于 Web 的系统，所以本方案中不予考虑。 GraphQL 调研了一下，它能够满足我们的第一个需求，前端可以定义接口，对后端接口依赖少。但是无法满足第二点，采用 GraphQL 的后端开发工作量很大，测试也麻烦，而且 GraphQL 太新，整个团队都没有使用的经验。 REST 有很多可用的代码生成系统可参考，比如 rails scaffold ／ django admin，不需要从零开始。所以综合考虑还是采用 REST 风格。

按照 Fielding 博士的说法，REST 只适用于应用软件的架构，不包括操作系统、网络软件和一些仅仅为得到系统支持而使用网络的架构风格 (例如，进程控制风格)。应用软件代表的是一个系统的“理解业务”(business-aware) 的那部分功能。

按照 REST 架构设计的 Web API 一般被成为 Restful API。 REST 在数据库类应用中使用广泛。针对数据库中的一张表，Restful 的 api 通过约定来定义好 CRUD 的全部接口 api，不需要前后端之间沟通接口的设计，而且各种语言都有针对单表的 CRUD 后端自动代码生成，能够减少后端的开发工作量。约定大于配置是一个很好的软件工程实践，能够大大减少软件开发的复杂性。下面就是一个 restful 的 api 约定：

操作	HTTP Method	URI
获取列表数据	GET	/表名 (.:format)
添加新数据	POST	/表名 (.:format)
修改已有数据	PUT	/表名/:id(.:format)
查看已有数据	GET	/表名/:id(.:format)
删除已有数据	DELETE	/表名/:id(.:format)

很多知名的软件和框架都采用了类似这套的约定，比如 rails 开发框架／ElasticSearch 搜索等。

当然针对实际的软件开发需求，REST 的规范还是太简单了。标准的 Restful 接口只有四个动作，CRUD。一个最常见的扩展（或者说是误用），就是使用更多的动作。因为常见的后端开发框架是 controller+action 的模式，一个 controller 对应一个资源，里面配置多个 action 对应前端用户的多个动作。典型的，比如一个帖子，点赞／取消赞是两个动作。然后随着业务的发展，还有锁帖／解锁操作，回复帖子／查看所有 0 回复帖子等等需要。于是就有了下面的这种 url 设计：

POST /topics/follow
POST /topics/unfollow
POST /topics/lock
POST /topics/unlock
POST /topics/reply
GET /topics/no_reply

慢慢的，接口越来越复杂，离原来的 Restful 风格越来越远。当然，有人觉得这种风格也不错。而 DHH 的观点是这种风格 url 需要改造为 Restful 的风格，比如对于点赞的场景，可以认为有一个资源是 topics/follows，然后这个资源有添加和删除两个操作。关于 DHH 对这种风格的讨论，可参考这个链接，这里是中文翻译版。

今年的 rubychina 大会上也有一场针对类似问题的分享，可以参考 [这个链接](https://speakerdeck.com/mechiland/reconsider-rest-chong-gou-jian-da-xing-railsying-yong-de-fang-shi

这还只是对单表资源的 CRUD 操作，我们碰到的 Restful 规范主要是缺失下面的一些部分：

查询／分页／排序的支持。Restful 接口只有一个列表的接口，对查询相关的功能没有约定。
批量操作的支持。Restful 接口默认只支持单个资源的操作，而实际的业务场景中经常需要有批量操作的需求，比如商品的批量上架、数据的批量删除等。
有关联的数据表的支持。Restful 只支持单个资源的 CRUD，而实际业务中经常有主子表的级联保存，关联表的查询等。

所以本方案主要考虑两点：

扩展 REST，针对上述三种场景约定好接口规范。目的是让前端程序员只需要知道接口约定，就可以针对所有的数据库表进行接口开发。无需提供详细的接口说明文档。
如何通过自动代码生成的方式实现这些规范，以减少后端开发的工作量。

3. Restful 扩展：单表批量操作（添加／更新／删除）

3.1 批量新增接口

REST 规范没有约定如何实现批量操作，也没有说明提交参数和返回值的格式。实践中，elasticsearch 提供了批量操作的入口/_bulk，统一处理所有的批量操作，可以在一次请求里完成索引／更新／删除等多个操作。本方案对批量操作的要求更严格，只支持单表数据的一种操作。对于批量新增接口，我们重用 Restful 的新增接口，只是提交的数据格式不一样。

单个新增的话，提交的是一个单个的 hash 对象

{
    "表名单数": {id:id, field:value,...}
}

批量新增的话，提交的里层数据是一个数组

{
    "表名复数": [{id:id1, field:value,...},{id:id2}...]
}

而且约定在所有的输入输出中，如果是集合对象，名字采用复数形式；如果是单个对象，名字采用单数形式。当然，还有一个约定是所有的主键的字段名都是“id”。请求中的 field 直接对应数据库的列名。如果 id 不传，则由数据库提供自动生成的主键。

3.2 批量修改接口

对于如何定义批量修改接口，有点左右为难。首先，无法按照批量新增的模式重用修改接口，因为 Restful 的单条数据修改接口“PUT /表名/:id”和单个 id 绑定了。如果严格参考 DHH 的做法，批量修改也需要抽象成一个资源，类似于点赞，而不应该增加一个动作。

但是我对这个做法不习惯，批量修改我认为还是和 CRUD 一个性质的。目前还是决定增加了一个动作 batch_update，也是整个约定里唯一增加的动作。批量修改接口的 url 地址是“/表名/batch_update.json”，提交的 json 数据格式和批量新增接口一致。以后也有可能统一提供一个类似 elasticsearch 的 bulk 接口。

3.3 批量删除接口

批量删除接口也没有按照 DHH 的说法抽象成资源，而是重用了 Restful 的删除接口，只是 id 的格式不一样。批量删除接口，一次传入多个 id，id 之间以英文逗号“,”分割。

所以针对批量操作，本方案增加了两个约定如下：

操作	HTTP Method	URI
批量修改数据	POST	/表名/batch_update(.:format)
批量删除数据	DELETE	/表名/:id,:id

4. Restful 扩展：单表查询

4.1 查询格式

单表的查询，uri 直接重用 rest 规范，但是要约定好查询的参数的传递规范。我们定义了下面这些查询的请求格式

s[field]=value
s[like[field]]=value
s[date[field]]=value
s[range[field]]=value
s[in[field]]=value
s[cmp[field,field]]=

分别代表精确查询／like 字符串模糊查询／date 日期范围查询／range 范围查询／in 枚举查询／cmp 比较查询。这些查询基本满足了 OLTP 业务的常见需求，报表统计类需求有专门的报表系统。

如果有多个查询条件，条件之间是逻辑与的关系。

s[field1]=value1&s[like[field2]]=value2

查询的 field 直接对应到数据库的字段。如果 field 有逗号“,”，则表示同时查询多个字段，其中一个满足条件即可，也就是 OR 查询。

"/warehouses.json?s[like[company,address]]=测试"

上面这个查询的意思是查找所有 company 包含‘测试’或者 address 包含‘测试’的所有仓库。

针对 date/range/in 查询，支持 value 中包含逗号“,”。以 range 查询为例，“1,5”代表范围是 1 到 5，",5"代表小于等于 5，"3,"代表大于等于 3。例如：

"/warehouses.json?s[range[id]]=1,5"
"/warehouses.json?s[range[id]]=,5"
"/warehouses.json?s[range[id]]=3,"

4.2 分页/排序/Count 计数

分页参数 page／per，排序参数 order，计数参数 count 之间都是可以自由组合的。例如：

"/warehouses.json?page=1"
"/warehouses.json?page=1&per=100"
"/warehouses.json?page=1&order=id+desc"
"/warehouses.json?page=1&per=100&count=1"

5. Restful 扩展：关联表支持

5.1 外键查询的支持

上一节提到的单表查询规范，其中的 field 字段，增加对特殊符号"."的支持，用于外键查询。这样 Field 可以包含三种类型：

单个key;
多字段的key，格式："key1,key2,..."
外键的key，格式：“key1.key2”。

其中，多字段的 key 的格式表示多个字段的 or 查询，上文已经提及。外键查询要求被查询的表有对应的外键字段。比如仓库属于公司，那么 warehouses 表有一个外键 company_id，company 有 id、name 字段，那么可以有下面的查询：

"warehouses.json?s[company.name]=测试公司"
"warehouses.json?s[range[company.id]]=1,5"

这两个查询的含义是显而易见的。

5.2 关联表查看

本系统支持在查看一条数据时，自动带出关联的父表的数据。同时也支持带出给定的几个关联子表数据：传递参数 many=表 1[,表 2]，比如：

GET warehouses/1.json?many=stores

查看编号为 1 的仓库的基本信息，同时给出这个仓库下面的所有库位的信息。这个查询要求 stores 表有一个外键指向 warehouses 表。

5.3 子表的级联新增和删除

主子表的级联保存

有很多业务场景需要支持在一个事务里保存主表和关联的多个子表的数据。级联保存的接口和批量保存的接口类似，只是提交的参数有区别。主子表新增的话，提交的数据格式如下：

{
    "主表单数": {id:id, field:value,...} ,
    "子表复数": [{id:id1, field:value,...},{id:id2,}...]
}

6. 小结

这篇文章主要介绍了项目采用的一种扩展的 restful 接口协议，基于该协议，前端程序员在知道数据库结构的情况下就可以开始项目开发了。由于供应链项目是一类成熟的项目，可以且必须参考已有系统的数据库设计（因为要保证旧系统的数据可以方便的迁移到新系统），所以数据库设计实际上是提前完成的。这和通常的 rails 项目不太相同，常见的 rails 项目数据库结构是在代码中定义的，随着开发的进行不断完善的，而不是提前给定的。

本文的下篇则会介绍到代码生成技术。

Puma 源代码分析－完结篇

ylt — Wed, 25 Mar 2015 23:33:05 +0800

puma 源代码分析之完结篇

这个系列的文章从 puma 的总体结构、启动流程开始分析起，到单进程／集群模式分析、IO 处理、http 协议解析，终于到了最后的完结篇。最后这部分主要讨论两个问题：1.Puma 是如何执行 rack app 来处理客户端请求的；2.运行时 puma server 如何接受和处理命令行工具 pumactl 发过来的请求。

处理客户端请求

Puma 是一个支持 rack 接口的 web 服务器，本节分析 puma 的 rack 接口部分，看看 puma 是如何执行 rack app 并输出 http 响应的。客户端请求的处理由 Server 类的 handle_request 方法完成。其中，req 代表客户端连接，lines 是输出缓冲区。本方法调用 rack app 并把响应写回给客户端。本方法有三种返回值：true/false/:async，分别代表启用 keep_alive, 不启用 keep_alive 和使用 socket-hijacking。

class Server
  # Given the request +env+ from +client+ and a partial request body
  # in +body+, finish reading the body if there is one and invoke
  # the rack app. Then construct the response and write it back to
  # +client+
  #
  # +cl+ is the previously fetched Content-Length header if there
  # was one. This is an optimization to keep from having to look
  # it up again.
  #
  def handle_request(req, lines)
    env = req.env
    client = req.io

    normalize_env env, client   ＃添加遵循Rack规范的一些env值

    env[PUMA_SOCKET] = client
    env[HIJACK_P] = true
    env[HIJACK] = req
    body = req.body
    head = env[REQUEST_METHOD] == HEAD
    env[RACK_INPUT] = body
    env[RACK_URL_SCHEME] =  env[HTTPS_KEY] ? HTTPS : HTTP

    # A rack extension. If the app writes #call'ables to this
    # array, we will invoke them when the request is done.
    #
    after_reply = env[RACK_AFTER_REPLY] = []

    begin
      begin
        status, headers, res_body = @app.call(env)   ＃这里调用了rack app

        return :async if req.hijacked

        status = status.to_i

        if status == -1
          unless headers.empty? and res_body == []
            raise "async response must have empty headers and body"
          end

          return :async
        end
      rescue StandardError => e
        @events.unknown_error self, e, "Rack app"

        status, headers, res_body = lowlevel_error(e)
      end

      content_length = nil
      no_body = head

      if res_body.kind_of? Array and res_body.size == 1
        content_length = res_body[0].bytesize
      end

      cork_socket client

      line_ending = LINE_END
      colon = COLON

      if env[HTTP_VERSION] == HTTP_11
        allow_chunked = true
        keep_alive = env[HTTP_CONNECTION] != CLOSE
        include_keepalive_header = false

        # An optimization. The most common response is 200, so we can
        # reply with the proper 200 status without having to compute
        # the response header.
        #
        if status == 200
          lines << HTTP_11_200
        else
          lines.append "HTTP/1.1 ", status.to_s, " ",
                       fetch_status_code(status), line_ending

          no_body ||= status < 200 || STATUS_WITH_NO_ENTITY_BODY[status]
        end
      else
      ......
      end

      response_hijack = nil

      headers.each do |k, vs|
        case k
        when CONTENT_LENGTH2
          content_length = vs
          next
        when TRANSFER_ENCODING
          allow_chunked = false
          content_length = nil
        when HIJACK
          response_hijack = vs
          next
        end

        if vs.respond_to?(:to_s)
          vs.to_s.split(NEWLINE).each do |v|
            lines.append k, colon, v, line_ending
          end
        else
          lines.append k, colon, line_ending
        end
      end

      if no_body
        if content_length and status != 204
          lines.append CONTENT_LENGTH_S, content_length.to_s, line_ending
        end

        lines << line_ending
        fast_write client, lines.to_s
        return keep_alive
      end

      if include_keepalive_header
        lines << CONNECTION_KEEP_ALIVE
      elsif !keep_alive
        lines << CONNECTION_CLOSE
      end

      unless response_hijack
        if content_length
          lines.append CONTENT_LENGTH_S, content_length.to_s, line_ending
          chunked = false
        elsif allow_chunked
          lines << TRANSFER_ENCODING_CHUNKED
          chunked = true
        end
      end

      lines << line_ending

      fast_write client, lines.to_s

      if response_hijack
        response_hijack.call client
        return :async
      end

      begin
        res_body.each do |part|
          if chunked
            fast_write client, part.bytesize.to_s(16)
            fast_write client, line_ending
            fast_write client, part
            fast_write client, line_ending
          else
            fast_write client, part
          end

          client.flush
        end

        if chunked
          fast_write client, CLOSE_CHUNKED
          client.flush
        end
      rescue SystemCallError, IOError
        raise ConnectionError, "Connection error detected during write"
      end

    ensure
      uncork_socket client

      body.close
      res_body.close if res_body.respond_to? :close

      after_reply.each { |o| o.call }
    end

    return keep_alive
  end

整个方法很长，但是逻辑不复杂。主要就是根据 rack app 的调用情况和 keep_alive/chunked/hijiack 等 http 选项，输出 http 响应的状态码／响应头部／响应体。其中最核心的执行 rack app 的代码只有一行：status, headers, res_body = @app.call(env)。此外，normalize_env 方法用于增加和修正一些 Rack 的 env 变量，代码如下：

# Given a Hash +env+ for the request read from +client+, add
# and fixup keys to comply with Rack's env guidelines.
#
def normalize_env(env, client)
  if host = env[HTTP_HOST]
    if colon = host.index(":")
      env[SERVER_NAME] = host[0, colon]
      env[SERVER_PORT] = host[colon+1, host.bytesize]
    else
      env[SERVER_NAME] = host
      env[SERVER_PORT] = default_server_port(env)
    end
  else
    env[SERVER_NAME] = LOCALHOST
    env[SERVER_PORT] = default_server_port(env)
  end

  unless env[REQUEST_PATH]
    # it might be a dumbass full host request header
    uri = URI.parse(env[REQUEST_URI])
    env[REQUEST_PATH] = uri.path

    raise "No REQUEST PATH" unless env[REQUEST_PATH]
  end

  env[PATH_INFO] = env[REQUEST_PATH]

  # From http://www.ietf.org/rfc/rfc3875 :
  # "Script authors should be aware that the REMOTE_ADDR and
  # REMOTE_HOST meta-variables (see sections 4.1.8 and 4.1.9)
  # may not identify the ultimate source of the request.
  # They identify the client for the immediate request to the
  # server; that client may be a proxy, gateway, or other
  # intermediary acting on behalf of the actual source client."
  #

  unless env.key?(REMOTE_ADDR)
    addr = client.peeraddr.last

    # Set unix socket addrs to localhost
    addr = "127.0.0.1" if addr.empty?

    env[REMOTE_ADDR] = addr
  end
end

最后看看处理客户端请求的循环的 process_client 方法。这个方法的核心是调用 handle_request 方法，然后根据返回值决定下一步的处理。如果 handle_request 返回 false，也就是没有 keep_alive，那么本方法执行完立刻关闭客户端连接；如果返回 true，那么就是 keep_alive，就会循环调用 handle_request，此时会重用同一个客户端连接处理多个 http 请求；如果 handle_request 返回 async，那么就是 socket hijack 模式，此时由 rack app 来直接处理 socket 连接，puma 也不关闭客户端 socket。关于 hijacking 的说明可以参考这篇文章rack socket hijacking。Socket hijack 模式可以用来实现 WebSocket 功能。

# Given a connection on +client+, handle the incoming requests.
#
# This method support HTTP Keep-Alive so it may, depending on if the client
# indicates that it supports keep alive, wait for another request before
# returning.
#
def process_client(client, buffer)
  begin
    close_socket = true

    while true
      case handle_request(client, buffer)
      when false
        return
      when :async
        close_socket = false
        return
      when true
        return unless @queue_requests
        buffer.reset

        unless client.reset(@status == :run)
          close_socket = false
          client.set_timeout @persistent_timeout
          @reactor.add client
          return
        end
      end
    end

  # The client disconnected while we were reading data
  rescue ConnectionError
    # Swallow them. The ensure tries to close +client+ down

  # The client doesn't know HTTP well
  rescue HttpParserError => e
    client.write_400

    @events.parse_error self, client.env, e

  # Server error
  rescue StandardError => e
    client.write_500

    @events.unknown_error self, e, "Read"

  ensure
    buffer.reset

    begin
      client.close if close_socket
    rescue IOError, SystemCallError
      # Already closed
    rescue StandardError => e
      @events.unknown_error self, e, "Client"
    end
  end
end

至此把 puma 处理 rack app 的流程总体上过了一遍。

pumactl 如何控制 puma 的运行状态

Pumactl 是一个命令行工具，用来控制 puma 的运行状态。Pumactl 可以通过两种手段来控制 puma，一个是 pid，另一个是 control_url。

＃!/usr/bin/env ruby
require 'puma/control_cli'
cli = Puma::ControlCLI.new ARGV.dup
cli.run

class ControlCLI
  def run
    start if @options[:command] == "start"
    prepare_configuration
    @options.has_key?(:control_url) ? send_request : send_signal
  end

我们先看通过 pid 控制 puma 的运行，这个方式简单一些，但是功能也受限。从代码中可以看到，通过 pid 控制 puma 其实使用的是标准的 unix 信号机制。但是仅使用进程 pid 无法支持 stats 和 reload-worker-directory 命令。

def send_signal
  ......
  case @options[:command]
  when "restart"
    Process.kill "SIGUSR2", pid

  when "halt"
    Process.kill "QUIT", pid

  when "stop"
    Process.kill "SIGTERM", pid

  when "stats"
    puts "Stats not available via pid only"
    return

  when "reload-worker-directory"
    puts "reload-worker-directory not available via pid only"
    return

  when "phased-restart"
    Process.kill "SIGUSR1", pid

  else
    message "Puma is started"
    return
  end

  message "Command #{@options[:command]} sent success"
end

要使用 control_url 来控制 puma，必须在启动 puma 的时候提供 control 相关的参数，比如：

puma --control tcp://127.0.0.1:9293 --control-token foo

然后，在启动 puma 的时候，会根据配置的 control 参数启动一个单独的 puma server，并执行一个单独的 rack app。

class Runner
   def start_control
     str = @options[:control_url]
     require 'puma/app/status'
     uri = URI.parse str
     app = Puma::App::Status.new @cli    ＃响应control请求时执行的rack app
     if token = @options[:control_auth_token]
       app.auth_token = token unless token.empty? or token == :none
     end

     control = Puma::Server.new app, @cli.events  ＃启动一个独立的puma server, 并执行内置的app
     control.min_threads = 0
     control.max_threads = 1

     case uri.scheme
     when "tcp"
       log "* Starting control server on #{str}"
       control.add_tcp_listener uri.host, uri.port
     when "unix"
       log "* Starting control server on #{str}"
       path = "#{uri.host}#{uri.path}"

       control.add_unix_listener path
     else
       error "Invalid control URI: #{str}"
     end

     control.run
     @control = control
   end

从代码中可以看出，如果使用 control_url 机制，会启动一个 puma server，并执行 Puma::App::Status 这个 app。也就是说，control_url 机制下的 puma 进程会监听两个不同的端口，一个执行启动者提供的 rack app，另一个执行自己内部的 Status 这个 app。

class Status
  def call(env)
    unless authenticate(env)
      return rack_response(403, 'Invalid auth token', 'text/plain')
    end

    case env['PATH_INFO']
    when /\/stop$/
      @cli.stop
      return rack_response(200, OK_STATUS)

    when /\/halt$/
      @cli.halt
      return rack_response(200, OK_STATUS)

    when /\/restart$/
      @cli.restart
      return rack_response(200, OK_STATUS)

    when /\/phased-restart$/
      if !@cli.phased_restart
        return rack_response(404, '{ "error": "phased restart not available" }')
      else
        return rack_response(200, OK_STATUS)
      end

    when /\/reload-worker-directory$/
      if !@cli.reload_worker_directory
        return rack_response(404, '{ "error": "reload_worker_directory not available" }')
      else
        return rack_response(200, OK_STATUS)
      end

    when /\/stats$/
      return rack_response(200, @cli.stats)
    else
      rack_response 404, "Unsupported action", 'text/plain'
    end
  end

可以看到，Status 是一个标准的 rack app 实现，提供一个 call 方法，接受一个 env 参数并返回 rack_response。下面看一下 stats 的实现：

 class Single < Runner
   def stats
     b = @server.backlog
     r = @server.running
     %Q!{ "backlog": #{b}, "running": #{r} }!
   end

 class Server
   def backlog
     @thread_pool and @thread_pool.backlog
   end

   def running
     @thread_pool and @thread_pool.spawned
   end
 end

class ThreadPool  
 def backlog
   @mutex.synchronize { @todo.size }
 end

可以看到，backlog 是线程池中等待执行的任务的个数，running 指当前线程池中的线程数量。

Puma 源代码分析－ HTTP 协议解析

ylt — Sun, 15 Mar 2015 00:44:25 +0800

puma 的 http 协议解析

总览

对一个 web 服务器来说，http 协议解析模块是性能关键的部分。为了性能考虑，puma 的 http 协议解析器是用 C 语言写 ruby 扩展实现的。这部分代码原来是 Zed A. Shaw 为 Mongrel 所写，后来被移植到了 Unicorn、Thin 和 Puma。

上一节分析 socket 的时候已经看到，当客户端连接的 socket 有数据可读的时候，解析 http 协议部分的代码是

require 'puma/puma_http11'

@parser = HttpParser.new
@parsed_bytes = @parser.execute(@env, @buffer, @parsed_bytes)
if @parser.finished?
  return ...
end

这里 parser 相关的方法就是 C 语言实现的。其涉及到的关键文件有：http11_parser.rl, http11_parser.h, http11_parser.c, puma_http11.c。其中 http11_parser.c 其实是由 http11_parser.rl 生成的。这里使用到了一个工具 Ragel，网址ragel。它是一个类似 lex 的正则表达式分析器生成工具。在 puma 中使用了 ragel 的格式描述 http 协议。这一章的代码可能是最难懂的，因为涉及到了 ragel/c/ruby 扩展等很多知识点。

http 协议解析的接口

Http 协议解析的关键部分是理解 puma_parser 结构，这是 ragel／c／ruby 之间进行数据交换的关键结构。

typedef struct puma_parser {
  int cs;               ＃ragel解析的当前状态
  size_t body_start;    ＃body开始
  int content_len;      ＃content长度
  size_t nread;         ＃已读
  size_t mark;          
  size_t field_start;   ＃http字段开始
  size_t field_len;     ＃http字段长度
  size_t query_start;   ＃query开始

  VALUE request;        ＃ruby对象request的c表示
  VALUE body;           ＃ruby对象body的c表示

  field_cb http_field;          ＃解析时碰到http的field时的回调
  element_cb request_method;    ＃解析时碰到request_method时的回调
  element_cb request_uri;
  element_cb fragment;
  element_cb request_path;
  element_cb query_string;
  element_cb http_version;
  element_cb header_done;

  char buf[BUFFER_LEN];

} puma_parser;

typedef void (*element_cb)(struct puma_parser* hp,
                           const char *at, size_t length);

typedef void (*field_cb)(struct puma_parser* hp,
                         const char *field, size_t flen,
                         const char *value, size_t vlen);

该结构首先被 ragel 使用，其中的 cs 是 ragel 预定义的一个变量，代表当前状态。当 ragel 分析输入时，碰到符合的规则会执行对应的动作（action）。动作中会给 field_start／field_len 之类的变量赋值，也会调用 http_field 等回调。而这些回调则是 ruby 的 c 扩展在其 init 方法中注入的。

http 协议的 ragel 描述

先看看 ragel 描述的 http 协议的部分代码：

%%{

  machine puma_parser_common;

  CRLF = "\r\n";

＃ character types
  CTL = (cntrl | 127);
  safe = ("$" | "-" | "_" | ".");
  extra = ("!" | "*" | "'" | "(" | ")" | ",");
  reserved = (";" | "/" | "?" | ":" | "@" | "&" | "=" | "+");
  unsafe = (CTL | " " | "\"" | "#" | "%" | "<" | ">");
  national = any -- (alpha | digit | reserved | extra | safe | unsafe);
  unreserved = (alpha | digit | safe | extra | national);
  escape = ("%" xdigit xdigit);
  uchar = (unreserved | escape);
  pchar = (uchar | ":" | "@" | "&" | "=" | "+");
  tspecials = ("(" | ")" | "<" | ">" | "@" | "," | ";" | ":" | "\\" | "\"" | "/" | "[" | "]" | "?" | "=" | "{" | "}" | " " | "\t");

＃ elements
  token = (ascii -- (CTL | tspecials));

＃ URI schemes and absolute paths
  scheme = ( alpha | digit | "+" | "-" | "." )* ;
  absolute_uri = (scheme ":" (uchar | reserved )*);

  path = ( pchar+ ( "/" pchar* )* ) ;
  query = ( uchar | reserved )* %query_string ;
  param = ( pchar | "/" )* ;
  params = ( param ( ";" param )* ) ;
  rel_path = ( path? %request_path (";" params)? ) ("?" %start_query query)?;
  absolute_path = ( "/"+ rel_path );

  Request_URI = ( "*" | absolute_uri | absolute_path ) >mark %request_uri;
  Fragment = ( uchar | reserved )* >mark %fragment;
  Method = ( upper | digit | safe ){1,20} >mark %request_method;

  http_number = ( digit+ "." digit+ ) ;
  HTTP_Version = ( "HTTP/" http_number ) >mark %http_version ;
  Request_Line = ( Method " " Request_URI ("#" Fragment){0,1} " " HTTP_Version CRLF ) ;

  field_name = ( token -- ":" )+ >start_field $snake_upcase_field %write_field;

  field_value = any* >start_value %write_value;

  message_header = field_name ":" " "* field_value :> CRLF;

  Request = Request_Line ( message_header )* ( CRLF @done );

main := Request;

}%%

其中的 machine 代表一个有限状态机器，它使用 ragel 定制化的正则表达式来表述，然后包含一些 action 的描述。以field_name = ( token -- ":" )+ >start_field $snake_upcase_field %write_field;为例，这一行的意思是 field_name 是任意的 token 但是不包含":"，这里的--就是 ragel 自定义的操作符，表示“Strong Difference”。这一行后面的三个字段则是 ragel 的用户动作（User Action）。其中>是进入动作（Enter Action）, $是全部转换动作 (All Transition Action), %是离开动作（Leave Action）。所以这个规则匹配的开始会执行 start_field，中间每个字符都会执行 snake_upcase_field，匹配完成执行 write_field。

  machine puma_parser;
  action start_field { MARK(field_start, fpc); }
  action snake_upcase_field { snake_upcase_char((char *)fpc); }
  action write_field { 
    parser->field_len = LEN(field_start, fpc);
  }

  action start_value { MARK(mark, fpc); }
  action write_value {
    parser->http_field(parser, PTR_TO(field_start), parser->field_len, PTR_TO(mark), LEN(mark, fpc));
  }
  action request_method { 
    parser->request_method(parser, PTR_TO(mark), LEN(mark, fpc));
  }

  include puma_parser_common "http11_parser_common.rl";

＃define LEN(AT, FPC) (FPC - buffer - parser->AT)
＃define MARK(M,FPC) (parser->M = (FPC) - buffer)  

static void snake_upcase_char(char *c)
{
    if (*c >= 'a' && *c <= 'z')
      *c &= ~0x20;
    else if (*c == '-')
      *c = '_';
}

在 ragel 的 action 里执行的是一些 c 函数。可以看到前面提到的 start_field／write_field 动作其实都是设置了 puma_parser 这个结构里一些字段，而 request_method 动作则会执行 puma_parser 里设置好的回调，这里的代码并不关心回调函数是什么。代码中的 fpc 是 ragel 预定义的变量，是指向当前字符的指针。

http 协议的解析

Http 协议的解析需要实现的接口函数如下：

int puma_parser_init(puma_parser *parser);
int puma_parser_finish(puma_parser *parser);
size_t puma_parser_execute(puma_parser *parser, const char *data,
                           size_t len, size_t off);
int puma_parser_has_error(puma_parser *parser);
int puma_parser_is_finished(puma_parser *parser);
＃define puma_parser_nread(parser) (parser)->nread

首先是初始化函数，这个函数很简单，主要就是初始化 puma_parser 结构体。其中的%% write init;是 ragel 提供的初始化语句，在生成的 c 代码中会被替换为 ragel 的初始化代码。

int puma_parser_init(puma_parser *parser)  {
  int cs = 0;
  %% write init;
  parser->cs = cs;
  parser->body_start = 0;
  parser->content_len = 0;
  parser->mark = 0;
  parser->nread = 0;
  parser->field_len = 0;
  parser->field_start = 0;
  parser->request = Qnil;
  parser->body = Qnil;

  return 1;
}

实现 http 协议解析的代码也很简单，真正的工作都是由 ragel 包办了，也就是%% write exec这一行。其中的 p/pe/cs 则都是 ragel 要求的预定义变量，分别代表"data pointer", "data end pointer", "current state"。

size_t puma_parser_execute(puma_parser *parser, const char *buffer, size_t len, size_t off)  {
  const char *p, *pe;
  int cs = parser->cs;
  p = buffer+off;
  pe = buffer+len;

  %% write exec;

  if (!puma_parser_has_error(parser))
    parser->cs = cs;
  parser->nread += p - (buffer + off);
  return(parser->nread);
}

然后是判断解析是否完成，是否有错误等的实现代码，也都比较简单。

int puma_parser_finish(puma_parser *parser)
{
  if (puma_parser_has_error(parser) ) {
    return -1;
  } else if (puma_parser_is_finished(parser) ) {
    return 1;
  } else {
    return 0;
  }
}

int puma_parser_has_error(puma_parser *parser) {
  return parser->cs == puma_parser_error;
}

int puma_parser_is_finished(puma_parser *parser) {
  return parser->cs >= puma_parser_first_final;
}

ruby 对象的 c 接口

最后看看如何在 ruby 中使用上面提供的 c 语言的 http 解析代码。关于如何编写 ruby 的 c 语言扩展，可以看看这个系列的文章。

首先来看看入口函数，它首先定义了模块 Puma 和类 HttpParser，然后定义了一些 ruby 中的全局的变量如 request_method 等，然后给 HttpParser 对象定义了一些方法如 new/execute/finish 等。

void Init_puma_http11()
{

  VALUE mPuma = rb_define_module("Puma");
  VALUE cHttpParser = rb_define_class_under(mPuma, "HttpParser", rb_cObject);

  DEF_GLOBAL(request_method, "REQUEST_METHOD");
  DEF_GLOBAL(request_uri, "REQUEST_URI");
  DEF_GLOBAL(fragment, "FRAGMENT");
  DEF_GLOBAL(query_string, "QUERY_STRING");
  DEF_GLOBAL(http_version, "HTTP_VERSION");
  DEF_GLOBAL(request_path, "REQUEST_PATH");

  eHttpParserError = rb_define_class_under(mPuma, "HttpParserError", rb_eIOError);
  rb_global_variable(&eHttpParserError);

  rb_define_alloc_func(cHttpParser, HttpParser_alloc);
  rb_define_method(cHttpParser, "initialize", HttpParser_init, 0);
  rb_define_method(cHttpParser, "reset", HttpParser_reset, 0);
  rb_define_method(cHttpParser, "finish", HttpParser_finish, 0);
  rb_define_method(cHttpParser, "execute", HttpParser_execute, 3);
  rb_define_method(cHttpParser, "error?", HttpParser_has_error, 0);
  rb_define_method(cHttpParser, "finished?", HttpParser_is_finished, 0);
  rb_define_method(cHttpParser, "nread", HttpParser_nread, 0);
  rb_define_method(cHttpParser, "body", HttpParser_body, 0);
  init_common_fields();

  Init_io_buffer(mPuma);
  Init_mini_ssl(mPuma);
}

＃define DEF_GLOBAL(N, val)   global_##N = rb_str_new2(val); rb_global_variable(&global_##N)

然后我们看看 HttpParser 的初始化实现，也就是在执行 ruby 代码HttpParser.new时，底层到底发生了什么。可以看到，当执行 new 的时候，先给 puma_parser 结构体分配了内存，然后设置了一些回调函数。前面提高的 ragel 的动作执行的时候，会执行这里设置的回调。ALLOC_N 是 ruby 提供的内存分配函数，相比于 malloc 直接分配，ALLOC_N 的功能更强，比如在内存不够的时候它会尝试先执行一次垃圾收集然后再分配内存。ALLOC_N 分配出去的内存必须使用 xfree 回收。

VALUE HttpParser_alloc(VALUE klass)
{
  puma_parser *hp = ALLOC_N(puma_parser, 1);
  TRACE();
  hp->http_field = http_field;
  hp->request_method = request_method;
  hp->request_uri = request_uri;
  hp->fragment = fragment;
  hp->request_path = request_path;
  hp->query_string = query_string;
  hp->http_version = http_version;
  hp->header_done = header_done;
  hp->request = Qnil;

  puma_parser_init(hp);

  return Data_Wrap_Struct(klass, HttpParser_mark, HttpParser_free, hp);
}

然后看看实际执行 http 协议解析的函数，这里的关键部分还是调用前面提到的 puma_parser_execute 函数，其它代码都是为了提供给 ruby 层使用而增加的封装。

VALUE HttpParser_execute(VALUE self, VALUE req_hash, VALUE data, VALUE start)
{
  puma_parser *http = NULL;
  int from = 0;
  char *dptr = NULL;
  long dlen = 0;

  DATA_GET(self, puma_parser, http);

  from = FIX2INT(start);
  dptr = rb_extract_chars(data, &dlen);

  if(from >= dlen) {
    rb_free_chars(dptr);
    rb_raise(eHttpParserError, "%s", "Requested start is after data buffer end.");
  } else {
    http->request = req_hash;
    puma_parser_execute(http, dptr, dlen, from);

    rb_free_chars(dptr);
    VALIDATE_MAX_LENGTH(puma_parser_nread(http), HEADER);

    if(puma_parser_has_error(http)) {
      rb_raise(eHttpParserError, "%s", "Invalid HTTP format, parsing fails.");
    } else {
      return INT2FIX(puma_parser_nread(http));
    }
  }
}

VALUE HttpParser_is_finished(VALUE self)
{
  puma_parser *http = NULL;
  DATA_GET(self, puma_parser, http);

  return puma_parser_is_finished(http) ? Qtrue : Qfalse;
}

最后看看一些 ragel 回调的实现。函数 http_field 就是把解析出来的 field 和 value 对设置到 ruby 的 hash 中。前面看到的 ragel 代码action write_value {parser->http_field(......)}会调用这里的 c 代码。


void http_field(puma_parser* hp, const char *field, size_t flen,
                                 const char *value, size_t vlen)
{
  VALUE v = Qnil;
  VALUE f = Qnil;

  VALIDATE_MAX_LENGTH(flen, FIELD_NAME);
  VALIDATE_MAX_LENGTH(vlen, FIELD_VALUE);

  v = rb_str_new(value, vlen);

  f = find_common_field_value(field, flen);

  if (f == Qnil) {
    /*
     * We got a strange header that we don't have a memoized value for.
     * Fallback to creating a new string to use as a hash key.
     */

    size_t new_size = HTTP_PREFIX_LEN + flen;
    assert(new_size < BUFFER_LEN);

    memcpy(hp->buf, HTTP_PREFIX, HTTP_PREFIX_LEN);
    memcpy(hp->buf + HTTP_PREFIX_LEN, field, flen);

    f = rb_str_new(hp->buf, new_size);
  }

  rb_hash_aset(hp->request, f, v);
}

其它一些 ragel 回调则都很简单，比如函数 request_method 则设置了 ruby 中 global_request_method 的值。

void request_method(puma_parser* hp, const char *at, size_t length)
{
  VALUE val = Qnil;

  val = rb_str_new(at, length);
  rb_hash_aset(hp->request, global_request_method, val);
}

void request_path(puma_parser* hp, const char *at, size_t length)
{
  VALUE val = Qnil;

  VALIDATE_MAX_LENGTH(length, REQUEST_PATH);

  val = rb_str_new(at, length);
  rb_hash_aset(hp->request, global_request_path, val);
}

void query_string(puma_parser* hp, const char *at, size_t length)
{
  VALUE val = Qnil;

  VALIDATE_MAX_LENGTH(length, QUERY_STRING);

  val = rb_str_new(at, length);
  rb_hash_aset(hp->request, global_query_string, val);
}

在 ruby 中通过调用 HttpParser.execute 解析输入的字符流，通过 parser.finished？判断是否解析完成，如果 ragel 的状态是 puma_parser_first_final，那么代表解析完成。

Puma 源代码分析－ IO 处理

ylt — Wed, 11 Mar 2015 18:37:22 +0800

puma 的 IO 处理分析

Puma 的 IO 总体架构

总体来看，puma 的 io 处理有三个循环：1. Server 里处理 Socket 连接建立的循环；2. Reactor 里处理连接就绪的循环；3. 线程池里处理就绪任务的循环。

第一步：所有的网络服务器，接入部分都是一个建立连接的循环。Puma 在接受到客户端的连接请求后，就初始化一个 Client 对象，并将其加入线程池。

第二步：所有建立的连接，如果还没有就绪，就加入到 Reactor 里等待其就绪。如果 Reactor 里有一个连接就绪，那么就把这个连接加入到线程池。

第三步：线程池不断从任务队列中取出任务，执行它。如果因为 io 还未就绪的原因导致任务无法执行，就把这个任务（Client 对象）再次加入到 Reactor 里。

这三个循环中，前面两个都是通过 pipe 接受外部控制的，第三个循环通过改变其@shutdown标志和@todo任务队列可以让其退出。

Reactor 与 Proactor 两种模式

Reactor 与 Proactor 是两种典型 io 事件处理模式。这两种模式都是让 io 数据的处理者只需要专心处理业务，而 io 事件的监听与通知则交给独立的第三方（一般称为事件分离者）。Reactor 模式是基于同步 I/O 的，而 Proactor 模式是和异步 I/O 相关的。

在 Reactor 模式中，事件分离者等待某个事件或者可应用或个操作的状态发生（比如文件描述符可读写，或者是 socket 可读写），事件分离者就把这个事件传给事先注册的事件处理者（回调函数），由后者来做实际的读写操作。

而在 Proactor 模式中，事件处理者 (或者代由事件分离者发起) 直接发起一个异步读写操作 (相当于请求)，而实际的工作是由操作系统来完成的。发起时，需要提供的参数包括用于存放读到数据的缓存区，读的数据大小，或者用于存放外发数据的缓存区，以及这个请求完后的回调函数等信息。事件分离者得知了这个请求，它默默等待这个请求的完成，然后转发完成事件给相应的事件处理者或者回调。

Reactor 模式中，实际的 io 读写还是需要事件处理者完成，而 Proactor 模式中，事件处理者只是接收 io 完成的通知，实际的 io 已经由操作系统完成了。这里针对 Reactor 与 Proactor 的讨论比较抽象，下面的分析中看到具体的代码的时候会清楚一些。

Puma 的 io 处理采用的是 Reactor 模式。

Socket 连接建立

先来看 Socket 连接建立的代码。前面提到，为了控制和退出这个循环，使用了 pipe 机制。所以整个循环其实有两块代码，处理 pipe 的代码和处理 socket 连接建立的代码。

class Server
  def initialize(app, events=Events.stdio, options={})
    @app = app
    @check, @notify = Puma::Util.pipe
    ......
  end

  def handle_servers
    begin
      check = @check
      sockets = [check] + @binder.ios   ＃同时监听pipe和连接端口
      pool = @thread_pool
      queue_requests = @queue_requests

      while @status == :run
        begin
          ios = IO.select sockets         ＃核心调用
          ios.first.each do |sock|
            if sock == check              ＃处理pipe的事件
              break if handle_check
            else
              begin
                if io = sock.accept_nonblock      ＃处理连接的建立
                  client = Client.new io, @binder.env(sock)
                  pool << client
                  pool.wait_until_not_full unless queue_requests
                end
              rescue SystemCallError
          end
        rescue Errno::ECONNABORTED
      end

      @events.fire :state, @status
      graceful_shutdown if @status == :stop || @status == :restart
      if queue_requests
        @reactor.clear! if @status == :restart
        @reactor.shutdown
      end
      ......
    end
    @events.fire :state, :done
  end

整个循环中最核心的是 select(2) 系统调用。要理解这块代码，先要熟悉 select 方法，这里先把 select 的说明整体摘抄下来：select monitors given arrays of IO objects, waits one or more of IO objects ready for reading, are ready for writing, and have pending exceptions respectively, and returns an array that contains arrays of those IO objects. It will return nil if optional timeout value is given and no IO object is ready in timeout seconds。文档在这里。

我们来分析这一行代码：ios = IO.select sockets。IO.select 一共有四个参数，其中 sockets 是 select 的第一个参数，代表需要等待可读的 IO 对象的数组，其它的三个参数这里没用到。返回值 ios 是一个最多三个元素的数组（分别表示可读的／可写的／异常的），其中的每一个元素也是一个素组。所以 ios.first 代表可读的所有 io 对象。

如果可读的 io 对象是自己的检查 pipe，那么调用 handle_check 处理 server 的停止／重启等；如果是有新的连接，那么初始化一个 Client 对象并加入到线程池。

def handle_check
  cmd = @check.read(1)

  case cmd
  when STOP_COMMAND
    @status = :stop
    return true
  when HALT_COMMAND
    @status = :halt
    return true
  when RESTART_COMMAND
    @status = :restart
    return true
  end

  return false
end

Reactor 的循环

下面来看看 Reactor 的循环。Reactor 里事件多路分发机制采用的也是 select(2) 系统调用，这是一种 io 多路复用的非阻塞同步 io。Reactor 的循环也是通过 pipe 来控制，所以循环代码有包含两块逻辑：pipe 处理和 socket 就绪处理。

class Reactor
  DefaultSleepFor = 5

  def initialize(server, app_pool)
    @server = server
    @app_pool = app_pool
    @ready, @trigger = Puma::Util.pipe
    @input = []
    @timeouts = []
    @sockets = [@ready]
  end

  def run_internal
    sockets = @sockets

    while true
      begin
        ready = IO.select sockets, nil, nil, @sleep_for      ＃核心调用
      rescue IOError => e
        if sockets.any? { |socket| socket.closed? }
          STDERR.puts "Error in select: #{e.message} (#{e.class})"
          STDERR.puts e.backtrace
          sockets = sockets.reject { |socket| socket.closed? }
          retry
        else
          raise
        end
      end

      if ready and reads = ready[0]
        reads.each do |c|
          if c == @ready             ＃处理pipe控制部分
            @mutex.synchronize do
              case @ready.read(1)
              when "*"
                sockets += @input
                @input.clear
              when "c"
                sockets.delete_if do |s|
                  if s == @ready
                    false
                  else
                    s.close
                    true
                  end
                end
              when "!"
                return
              end
            end
          else                        ＃处理socket部分
            begin
              if c.try_to_finish
                @app_pool << c      ＃可以处理的加入线程池
                sockets.delete c
              end

            # The client doesn't know HTTP well
            rescue HttpParserError => e
              c.write_400
              c.close

              sockets.delete c

              @events.parse_error @server, c.env, e
            rescue StandardError => e
              c.write_500
              c.close

              sockets.delete c
            end
          end
        end
      end

      unless @timeouts.empty?
        @mutex.synchronize do
          now = Time.now

          while @timeouts.first.timeout_at < now
            c = @timeouts.shift
            c.write_408 if c.in_data_phase
            c.close
            sockets.delete c

            break if @timeouts.empty?
          end

          calculate_sleep
        end
      end
    end
  end

代码中的 pipe 控制逻辑有三种情况：“”,"c"和"!"。“”代表增加一个待监控的客户端 socket 连接，"c"代表清空 reactor 中的 sockets 连接，"!"代表关闭 reactor。下面是给 reactor 增加客户端连接的方法，可以看到主要就是把连接 c 加入到@input变量中，然后向 pipe 写入"*"。这样在主循环中收到 pipe 的写入字符就知道要增加一个客户端连接了。

def add(c)
  @mutex.synchronize do
    @input << c
    @trigger << "*"

    if c.timeout_at
      @timeouts << c
      @timeouts.sort! { |a,b| a.timeout_at <=> b.timeout_at }
      calculate_sleep
    end
  end
end

循环中的另外一半处理 socket 连接。Socket 连接就绪时，通过运行 try_to_finish 判断 http 请求是否已经可以处理，如果可以的话，把 socket 连接加入到线程池。其它的大部分代码都是处理异常的，http 协议错误返回 400，连接超时错误返回 408，其它的错误都返回 500。

class Client
  def try_to_finish
    return read_body unless @read_header
    data = @io.read_nonblock(CHUNK_SIZE)  ＃reactor模式下，还是需要事件处理方自己读io
    @buffer << data
    @parsed_bytes = @parser.execute(@env, @buffer, @parsed_bytes)
    if @parser.finished?
      return setup_body
    end
    false
  end

从上面的代码可以看出，reactor 模式下还是需要事件处理方自己读 io。这是 reactor 模式与 proactor 的区别。当采用 proactor 模式，io 是操作系统完成的，事件处理方只需要处理 io 完成后的部分。代码中处理 http 协议解析的部分parser.execute其实是 C 语言实现的，这部分后面再单独分析。先看看 parser 完成后设置 body 的部分。

class Client
  EmptyBody = NullIO.new

  def setup_body
    @in_data_phase = true
    body = @parser.body
    cl = @env[CONTENT_LENGTH]

    unless cl
      @buffer = body.empty? ? nil : body
      @body = EmptyBody
      @requests_served += 1
      @ready = true
      return true
    end

    remain = cl.to_i - body.bytesize

    if remain <= 0
      @body = StringIO.new(body)
      @buffer = nil
      @requests_served += 1
      @ready = true
      return true
    end

    if remain > MAX_BODY      ＃1024 * (80 + 32)
      @body = Tempfile.new(Const::PUMA_TMP_BASE)
      @body.binmode
    else
      # The body[0,0] trick is to get an empty string in the same
      # encoding as body.
      @body = StringIO.new body[0,0]
    end

    @body.write body
    @body_remain = remain
    @read_header = false
    return false
  end

从代码中可以看出，body 存在三种可能，如果 http 请求没有 body 部分，那么就是 EmptyBody；如果 body 大于 112Kb，那么 body 的内容独立保存为一个 Tempfile；其它情况下，body 是一个 StringIO 对象。

线程池

最后来看看线程池的处理循环。

class ThreadPool
  def initialize(min, max, *extra, &block)
    @not_empty = ConditionVariable.new
    @not_full = ConditionVariable.new
    @mutex = Mutex.new
    @todo = []      ＃待处理任务
    @workers = []      ＃所有的工作线程
    @mutex.synchronize do
      @min.times { spawn_thread }
    end
    ......
  end

  def spawn_thread
    @spawned += 1

    th = Thread.new do
      todo  = @todo
      extra = @extra.map { |i| i.new }

      while true
        work = nil
        continue = true
        mutex.synchronize do
          while todo.empty?
            if @trim_requested > 0
              @trim_requested -= 1
              continue = false
              break
            end

            if @shutdown
              continue = false
              break
            end

            @waiting += 1
            not_full.signal
            not_empty.wait mutex
            @waiting -= 1
          end

          work = todo.shift if continue  ＃取出任务
        end
        break unless continue
        block.call(work, *extra)     # 实际执行任务
      end

      mutex.synchronize do
        @spawned -= 1
        @workers.delete th
      end
    end

    @workers << th
    th
  end

线程池里有多个工作线程，保存在@workers中。每一个工作线程有一个 while 循环，不断从任务队列@todo中取可以执行的任务。线程之间用 mutex 进行同步。每一个任务的实际执行代码是block.call(work, *extra)，其中的 block 是线程池在初始化的时候传递进来的，而 work 是一个 Client 对象。下面是 block 的代码：

class Server
  def run
    ......
    @thread_pool = ThreadPool.new(@min_threads,
                                  @max_threads,
                                  IOBuffer) do |client, buffer|
      process_now = false
      begin
        if queue_requests
          process_now = client.eagerly_finish
        else
          client.finish
          process_now = true
        end
      rescue HttpParserError => e
        client.write_400
        client.close

        @events.parse_error self, client.env, e
      rescue ConnectionError
        client.close
      else
        if process_now
          process_client client, buffer
        else
          client.set_timeout @first_data_timeout
          @reactor.add client
        end
      end
    end

可见，线程池执行的 block 代码块是 Server 启动的时候在初始化 ThreadPool 时设置的。实际的 http 请求处理在 process_client 方法中处理，这块代码下一篇再分析。对于现在还不能处理的客户端，把它加入 reactor 中。

下面是把任务加入到线程池的代码：

class ThreadPool
  def <<(work)
    @mutex.synchronize do
      if @shutdown
        raise "Unable to add work while shutting down"
      end

      @todo << work

      if @waiting < @todo.size and @spawned < @max
        spawn_thread
      end

      @not_empty.signal
    end
  end

当线程池初始化的时候，先执行@min次spawn_thread方法，然后在加任务的时候，如果线程数还没有达到@max，动态增加线程。

最后，看一下如何停止线程池：

def shutdown
  @mutex.synchronize do
    @shutdown = true
    @not_empty.broadcast
    @not_full.broadcast

    @auto_trim.stop if @auto_trim
  end

  # Use this instead of #each so that we don't stop in the middle
  # of each and see a mutated object mid #each
  if !@workers.empty?
      @workers.first.join until @workers.empty?
  end

  @spawned = 0
  @workers = []
end

输出

Puma 对输入的 socket 连接的处理很复杂，而对输出的处理则简单很多，代码如下：

def fast_write(io, str)
  n = 0
  while true
    begin
      n = io.syswrite str
    rescue Errno::EAGAIN, Errno::EWOULDBLOCK
      if !IO.select(nil, [io], nil, WRITE_TIMEOUT)
        raise ConnectionError, "Socket timeout writing data"
      end

      retry
    rescue  Errno::EPIPE, SystemCallError, IOError
      raise ConnectionError, "Socket timeout writing data"
    end

    return if n == str.bytesize
    str = str.byteslice(n..-1)
  end
end

所有的输出最后都是调用 syswrite 实现的。Syswrite 是一种底层的写方法，它在写数据时不使用 ruby 层的缓冲。Syswrite 不能和普通的 write 混合使用。

Puma 源代码分析－集群模式

ylt — Sun, 08 Mar 2015 21:34:06 +0800

Puma 的集群运行模式

Puma 集群的运行时结构

以集群模式启动的 Puma 服务器会有一个进程是 master 进程，然后有多个 worker 进程。Master 进程是通过 fork 的方式创建 worker 进程的，所以 master 进程是主进程，worker 进程是子进程。进程间通信采用的是 pipe 机制，每个 pipe 都是一对有两个元素的 io 对象，其中一个 io 对象只用于写，另一个 io 对象只用于读。

要理解集群的运行，一定要先理解 pipe 的工作原理，其官方文档在ruby pipe.

Puma 的运行时结构如图所示。

在运行时，Puma 的 Master/worker 进程间有两个 pipe，一个 pipe 用于 worker 进程报告给 master 进程自己的状态，另外一个 pipe 用于 worker 进程检查 master 进程有没有退出。代码中 pipe 相关的变量有 6 个，3 读 3 写，按执行顺序出现的次序如下：

read, @wakeup = Puma::Util.pipe
@check_pipe, @suicide_pipe = Puma::Util.pipe
@master_read, @worker_write = read, @wakeup

这段代码很奇葩，明明只有两个 pipe，只应该有 2 读 2 写，为什么偏偏多定义一组，而且是简单变量复制的方式多定义一组？仔细分析代码发现，read 和@wakeup这一组 pipe，只有 master 进程向@wakeup写内容，而且只有一处写。

def wakeup!
  begin
    @wakeup.write "!" unless @wakeup.closed?
  rescue SystemCallError, IOError
  end
end

而@master_read和@worker_write这一组 pipe，@master_read其实没有被使用，worker 进程有两处向@worker_write写内容。一处是 worker 进程内的 server 启动后，通过写"b#{Process.pid}\n"通知 master 进程；一处是 worker 进程内的独立线程，每 5 秒钟写一次"p#{Process.pid}\n"，报告 master 进程自己的状态。

def worker(index, master)
  server = start_server
  @worker_write << "b#{Process.pid}\n"

  Thread.new(@worker_write) do |io|
    payload = "p#{Process.pid}\n"

    while true
      sleep 5
      io << payload
    end
  end

所以图中的 state report pipe 其实有两个独立的用途，一个用途是主进程自己使用，用于 wakeup，另一个用途是子进程报告状态。因为有两种独立的用途，所以定义了两组体现用途的名字。

在 Master 进程中，有一个@workers对象，保存的是 Worker 的数组，这个 Worker 对象其实不是真的 worker，而只是子进程 worker 信息的记录对象。因为在不同的进程中，ruby 对象是完全对立的，主进程中的@workers对象和子进程中的任何 ruby 对象都没有关系。

class Worker
  def initialize(idx, pid, phase, options)
    @index = idx
    @pid = pid
    @phase = phase
    @stage = :started
    @signal = "TERM"
    @options = options
    @first_term_sent = nil
    @last_checkin = Time.now
  end

  attr_reader :index, :pid, :phase, :signal, :last_checkin

Worker 对象的几个关键属性为：index 指子进程编号，从 0 开始；pid 指子进程的 pid，phase 指第几次 phased_restart，signal 指要发送给子进程的信号，last_checkin 指子进程最后一次报告状态的时间。

Master 主进程并不实际处理 Web 请求，而是由 worker 进程来处理。worker 进程启动的时候，会在内部启动一个 puma 的 server。

Puma 集群的启动过程

集群的启动执行的是 Cluster 类的 run 方法。其中绑定端口，写状态文件之类的函数和单进程模式是一样的，这里就不重复说明了。可以看到，集群模式多了很多信号处理的代码，pipe 处理的代码，以及最关键的启动 worker 进程的代码 spawn_workers。

class Cluster < Runner
  def run
    @status = :run
    output_header "cluster"
    log "* Process workers: #{@options[:workers]}"
    @cli.binder.parse @options[:binds], self

    read, @wakeup = Puma::Util.pipe

    Signal.trap "SIGCHLD" do
      wakeup!
    end

    Signal.trap "TTIN" do
      @options[:workers] += 1
      wakeup!
    end

    Signal.trap "TTOU" do
      @options[:workers] -= 1 if @options[:workers] >= 2
      @workers.last.term
      wakeup!
    end

    master_pid = Process.pid

    Signal.trap "SIGTERM" do
      if Process.pid != master_pid
        log "Early termination of worker"
        exit! 0
      else
        stop
      end
    end

    @check_pipe, @suicide_pipe = Puma::Util.pipe

    redirect_io
    start_control
    @cli.write_state

    @master_read, @worker_write = read, @wakeup

    spawn_workers

    Signal.trap "SIGINT" do
      stop
    end

    @cli.events.fire_on_booted!

    begin
      while @status == :run
        ... #主进程的主循环，见下一小节
      end
    end
  end

主进程一共处理 5 种类型的信号：SIGCHLD 让主进程 wakeup，TTIN 增加一个 worker 进程，TTOU 减少一个 worker 进程，SIGTERM 终止主进程，SIGINT 也是终止进程。

Master 进程的主循环

集群的主进程启动完成后，执行下面的主循环。循环中读取 read 对象，这个 read 就是前面提到的状态检查 pipe 的读取对象。该 pipe 一共可能写入三种数据，"!","b#{pid}","p#{pid}"，所以读取的时候判断是哪种情况并相应进行处理。

  begin
    while @status == :run
      begin
        res = IO.select([read], nil, nil, 5)

        force_check = false

        if res
          req = read.read_nonblock(1)
          next if !req || req == "!"
          pid = read.gets.to_i
          if w = @workers.find { |x| x.pid == pid }
            case req
            when "b"
              w.boot!
              log "- Worker #{w.index} (pid: #{pid}) booted, phase: #{w.phase}"
              force_check = true
            when "p"
              w.ping!
            end
          else
            log "! Out-of-sync worker list, no #{pid} worker"
          end
        end

        if @phased_restart
          start_phased_restart
          @phased_restart = false
        end
        check_workers force_check
      rescue Interrupt
        @status = :stop
      end
    end

    stop_workers unless @status == :halt
  ensure
    @check_pipe.close
    @suicide_pipe.close
    read.close
    @wakeup.close
  end
end

当主进程收到"b#{pid}"和"p#{pid}"格式的数据时，根据 pid 找到 Worker 对象，然后执行该对象的 boot! 和 ping! 方法，主要就是更新 Worker 的最后签到信息。

class Worker
  def boot!
    @last_checkin = Time.now
    @stage = :booted
  end

  def ping!
    @last_checkin = Time.now
  end

Puma 集群的 Worker 的启动过程

上面提到，Master 进程会调用 spawn_workers 方法启动 worker 进程，这里就是相关代码：

def spawn_workers
  diff = @options[:workers] - @workers.size

  master = Process.pid

  diff.times do
    idx = next_worker_index

    pid = fork { worker(idx, master) }
    @cli.debug "Spawned worker: #{pid}"
    @workers << Worker.new(idx, pid, @phase, @options)
    @options[:after_worker_boot].each { |h| h.call }
  end

  if diff > 0
    @phased_state = :idle
  end
end

其中的核心部分就是 fork 调用创建一个新的 worker 进程，该进程会立即执行 worker(idx, master) 方法。有 java 语言背景的人，容易误认为这里的 worker 方法是 Worker 类的构造函数，其实它们之间没有关系。

def worker(index, master)
  title = "puma: cluster worker #{index}: #{master}"
  title << " [#{@options[:tag]}]" if @options[:tag]
  $0 = title

  Signal.trap "SIGINT", "IGNORE"

  @workers = []
  @master_read.close
  @suicide_pipe.close

  Thread.new do
    IO.select [@check_pipe]
    log "! Detected parent died, dying"
    exit! 1
  end

  hooks = @options[:before_worker_boot]
  hooks.each { |h| h.call(index) }

  server = start_server

  Signal.trap "SIGTERM" do
    server.stop
  end

  begin
    @worker_write << "b#{Process.pid}\n"
  rescue SystemCallError, IOError
    STDERR.puts "Master seems to have exitted, exitting."
    return
  end

  Thread.new(@worker_write) do |io|
    payload = "p#{Process.pid}\n"

    while true
      sleep 5
      io << payload
    end
  end

  server.run.join

  hooks = @options[:before_worker_shutdown]
  hooks.each { |h| h.call(index) }
ensure
  @worker_write.close
end

从代码中可以看出，worker 进程忽略 SIGINT 信号，收到 SIGTERM 信号时会调用 server.stop。但是如果 start_server 还没有调用的时候，worker 进程就收到了 SIGTERM 信号，那么 worker 进程会执行 exit。把主子进程两处定义的 SIGTERM 处理函数放在一起会更清楚一些。

Signal.trap "SIGTERM" do
  # The worker installs their own SIGTERM when booted.
  # Until then, this is run by the worker and the worker
  # should just exit if they get it.
  if Process.pid != master_pid
    log "Early termination of worker"
    exit! 0
  else
    stop
  end
end

Signal.trap "SIGTERM" do
  server.stop
end

因为 Linux 的 fork 创建进程时是写时拷贝的，所以当主进程设置的 SIGTERM 的处理代码，而子进程还没有修改时，子进程执行的也是同样的处理代码。而当子进程设置了 SIGTERM 的处理代码，主子进程各自拥有独立的 SIGTERM 的处理代码。

由于子进程不需要@workers对象，所以将@workers置空。子进程中不需要的 pipe 端口也关闭。子进程中有一个单独的线程来判断主进程是否退出。

Thread.new do
  IO.select [@check_pipe]
  log "! Detected parent died, dying"
  exit! 1
end

前面提到@check_pipe和@suicide_pipe是一对读写的 pipe。但是实际上没有任何代码往@suicide_pipe里写数据。所以 IO.select 返回的唯一情况就是@suicide_pipe被关闭了。此时主进程一定挂了。

当 worker 进程执行了 start_server 以后，会通过 pipe 写状态数据“b#{pid}”和"p#{pid}"，这部分代码已经分析过了。最后，worker 进程执行 server.run.join 来实际处理 web 请求。

Puma 源代码分析－单进程模式

ylt — Tue, 03 Mar 2015 10:26:44 +0800

Puma 的单进程运行模式

Puma 的类结构

在 puma 的启动过程代码中可以看到，负责单进程运行模式的类是 Single。在分析单进程运行模式之前，先总体看一下 puma 的单进程／集群架构。其类图如下所示，可以看出很像策略模式。

最右边是 puma 的启动入口类 PUAM::CLI，它包含一个成员变量@runner，属于 Runner 类。Runner 类有两个子类 Single 和 Cluster，分别负责单进程和集群运行模式。Single 和 Cluster 都提供一个 run 接口，CLI 的 run 方法会调用对应类的 run 方法。可以看出，这类似 GOF 的策略模式。但是 ruby 是动态语言，puma 的作者其实应该不是按照策略模式来实现这套框架的。

下面是 puma 早期的代码：

clustered = @options[:workers] > 0
if clustered
  run_cluster
else
  run_single
end

可见在 puma 早期，单进程执行 run_single 方法，集群执行 run_cluster 方法，没有 Runner/Single/Cluster 的类继承体系，CLI 里直接写单进程和集群的运行模式代码。

所以，现在的这个架构是逐步重构出来的。Single 和 Cluster 有很多雷同的代码，于是增加一个 Runner 类，把共同的代码提取到基类中，形成了现在的架构。我自己本人也是这样的编程习惯，通过不断的重构，清除重复代码，厘清代码的结构。

Runner 中有四个成员变量，分别是 cli／options／app／control，各代表命令行启动类，命令行参数类、配置的 rack app，运行时控制 puma 的 PUMA::ControlCLI 类。这四个类对单进程和多进程来说都是一样的。然后 Single 包含一个 PUAM::Server 类，而 Cluster 则包含一个 PUMA::Worker 的数组，这是单进程与集群模式真正有区别的地方。

单进程的执行流程

单进程的执行流程由 Single 类的 run 方法实现，它首先判断是否要以 daemon 的方法运行 puma，然后加载配置文件并确定监听哪些网络接口，接着把 puma 的进程 pid 以及状态信息写入状态文件中，然后启动运行时控制服务器的网络接口，然后通知启动监听者 puma 启动了，最后是运行 Server 类的 run 方法。

class Single < Runner
    def run
       if daemon?
         log "* Daemonizing..."
         Process.daemon(true)
         redirect_io
       end
      load_and_bind
      @cli.write_state
      start_control
      @server = server = start_server
      @cli.events.fire_on_booted!
      begin
        server.run.join
      rescue Interrupt
        # Swallow it
      end
end

绑定网络端口

绑定网络端口的实现代码如下：

class Runner
    def load_and_bind
      ……
      begin
        @app = @cli.config.app
      rescue Exception => e
        log "! Unable to load application: #{e.class}: #{e.message}"
        raise e
      end
      @cli.binder.parse @options[:binds], self  ＃实际绑定网络接口发生在这里
    end
end

首先加载 Rack 的@app，然后调用 Binder 类的 parse 方法实现网络绑定端口的解析和绑定。我感觉这个 parse 方法名字取的不好，叫 parse_and_bind 会更合适一些。另外一个违反直觉的是启动 TCPServer 的代码在 Binder 类中，而不在 Server 类中。下面看看 parse 方法的实现：

class Binder
    def parse(binds, logger)
      binds.each do |str|
        uri = URI.parse str
        case uri.scheme
        when "tcp"
          params = Rack::Utils.parse_query uri.query
          opt = params.key?('low_latency')
          bak = params.fetch('backlog', 1024).to_i
          logger.log "* Listening on #{str}"
          io = add_tcp_listener uri.host, uri.port, opt, bak
          @listeners << [str, io]
        when "unix"
          path = "#{uri.host}#{uri.path}".gsub("%20", " ")
          logger.log "* Listening on #{str}"
          umask = nil
          mode = nil
          if uri.query
            params = Rack::Utils.parse_query uri.query
            if u = params['umask']
              # Use Integer() to respect the 0 prefix as octal
              umask = Integer(u)
            end
            if u = params['mode']
              mode = Integer('0'+u)
            end
          end
          io = add_unix_listener path, umask, mode
          @listeners << [str, io]
        when "ssl"
          ......
         end
    end
end

这里的核心代码是 add_tcp_listener 和 add_unix_listener，分别启动 TCPServer 和 UNIXServer 并监听对应的网络端口。Puma 可以一次监听多个网络端口，其中 unix 快于 tcp，tcp 快于 ssl。由于实际应用中，ssl 都是前端接入的 web 服务器做 ssl offloading，所以这里的 ssl 相关代码就不分析了。

def add_tcp_listener(host, port, optimize_for_latency=true, backlog=1024)
  host = host[1..-2] if host[0..0] == '['
  s = TCPServer.new(host, port)
  if optimize_for_latency
    s.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
  end
  s.setsockopt(Socket::SOL_SOCKET,Socket::SO_REUSEADDR, true)
  s.listen backlog
  @ios << s
  s
end

def add_unix_listener(path, umask=nil, mode=nil)
  @unix_paths << path
  ......
  s = UNIXServer.new(path)
  @ios << s
  env = @proto_env.dup
  env[REMOTE_ADDR] = "127.0.0.1"
  @envs[s] = env
  s
end

写状态文件

当网络端口绑定以后，下一步是写入 pid 文件和状态文件，这两个文件的地址都是在 config 文件中通过 pidfile／state_path 命令配置的。

def write_state
  write_pid
  require 'yaml'
  if path = @options[:state]
    state = { "pid" => Process.pid }
    cfg = @config.dup
    state["config"] = cfg
    File.open(path, "w") do |f|
      f.write state.to_yaml
    end
  end
end

def write_pid
  if path = @options[:pidfile]
    File.open(path, "w") do |f|
      f.puts Process.pid
    end
    cur = Process.pid
    at_exit do
      if cur == Process.pid
        delete_pidfile
      end
    end
  end
end

写状态文件的代码很简单，基本就是把 Configuration 的对象实例序列化为 yaml 格式并写入文件中。写 pid 文件也很简单，只是 ruby 进程退出的时候要把老的 pid 文件删除。

下一步是启动 puma 的 control server，这是通过在 config 文件中配置 control_url 实现的。这块代码和主流程没有太大关系，先放放。

启动 Server

class Runner
  def start_server
    min_t = @options[:min_threads]
    max_t = @options[:max_threads]

    server = Puma::Server.new app, @cli.events, @options
    server.min_threads = min_t
    server.max_threads = max_t
    server.inherit_binder @cli.binder

    if @options[:mode] == :tcp
      server.tcp_mode!
    end
    unless development?
      server.leak_stack_on_error = false
    end
    server
  end

启动 Server 的方法 start_server 其实只是初始化了一个 Server 类的实例，赋值一些变量。

class Server
  def initialize(app, events=Events.stdio, options={})
    @app = app
    @events = events
    @check, @notify = Puma::Util.pipe
    @status = :stop
    @min_threads = 0
    @max_threads = 16
    @auto_trim_time = 1
    @thread = nil
    @thread_pool = nil
    @persistent_timeout = PERSISTENT_TIMEOUT
    @binder = Binder.new(events)
    @own_binder = true
    @first_data_timeout = FIRST_DATA_TIMEOUT
    @leak_stack_on_error = true
    @options = options
    @queue_requests = options[:queue_requests].nil? ? true : options[:queue_requests]
    ENV['RACK_ENV'] ||= "development"
    @mode = :http
  end

一个 Server 类用来服务一个 rack app。

boot 的事件通知

当 Server 初始化完成以后，通知事件监听者 puma 启动了。

class Events
  def fire_on_booted!
    @on_booted.each { |b| b.call }
  end

Server 的 run 方法

单进程模式的最后一步是调用 Server 的 run 方法。如果 background 设置为 true，那么会在一个新线程中运行实际的 handle_servers 代码，否则会同步执行。

class Server  
  def run(background=true)
    BasicSocket.do_not_reverse_lookup = true
    @events.fire :state, :booting
    @status = :run
    queue_requests = @queue_requests
    @thread_pool = ThreadPool.new(@min_threads,
                                  @max_threads,
                                  IOBuffer) do |client, buffer|
      ＃当有数据来的时候的回调block，后面详细分析io代码时分析此处省略的代码。
    end
    if queue_requests
      @reactor = Reactor.new self, @thread_pool
      @reactor.run_in_thread
    end
    @events.fire :state, :running
    if background
      @thread = Thread.new { handle_servers }
      return @thread
    else
      handle_servers
    end
  end

这一章里就不讨论 io 处理部分的代码（io 也是最复杂的一块），先看总体流程。

def handle_servers
  begin
    check = @check
    sockets = [check] + @binder.ios
    pool = @thread_pool
    queue_requests = @queue_requests

    while @status == :run
      begin
        ios = IO.select sockets
        ＃网络数据处理部分，后面详细分析io代码时分析此处省略的代码。
      rescue Errno::ECONNABORTED
        # client closed the socket even before accept
        client.close rescue nil
      rescue Object => e
        @events.unknown_error self, e, "Listen loop"
      end
    end

    @events.fire :state, @status
    graceful_shutdown if @status == :stop || @status == :restart
    if queue_requests
      @reactor.clear! if @status == :restart
      @reactor.shutdown
    end
    @check.close
    @notify.close
    if @status != :restart and @own_binder
      @binder.close
    end
  end
  @events.fire :state, :done
end

Puma 服务器通过@status变量控制其运行。当@status为:run 的时候，服务器处于运行状态，当外部操作导致@status变化时，puma 进入关闭／重启流程。

Puma 源代码分析－启动流程

ylt — Sat, 28 Feb 2015 16:42:59 +0800

Puma 的启动方式

puma 有两种启动方式：一种是通过标准的 rack 接口启动，一种是通过 puma 提供的命令行工具启动。

rack 接口

首先，Puma 会把自己设置为缺省的 rack handler，见文件 lib/puma/rack_default.rb

module Rack::Handler
  def self.default(options = {})
    Rack::Handler::Puma
  end
end

然后，在 Rack::Handler::Puma 的 run 方法中启动 puma，见文件 lib/rack/handler/puma.rb

def self.run(app, options = {})
  ......
  server   = ::Puma::Server.new(app)
  min, max = options[:Threads].split(':', 2)

  puts "Puma #{::Puma::Const::PUMA_VERSION} starting..."
  puts "* Listening on tcp://#{options[:Host]}:#{options[:Port]}"

  server.add_tcp_listener options[:Host], options[:Port]
  server.min_threads = min
  server.max_threads = max
  yield server if block_given?

  begin
    server.run.join
  rescue Interrupt
    puts "* Gracefully stopping, waiting for requests to finish"
    server.stop(true)
    puts "* Goodbye!"
  end
end

run 方法中的参数 app 是一个 rack 应用，options 只支持主机名／端口号／线程数／日志等有限的几个参数。从代码中可见，rack 接口启动 puma 只监听 tcp 端口，且使用单进程模式，不支持集群。所以通过 rack 接口启动 puma 不能完全利用 puam 的高级功能。

通过下面的命令都会以 rack 接口启动 puma：

rackup -s Puma
rails s Puma

命令行工具 bin/puma

另外一种启动 puma 的方法是通过命令行的 bin/puma 命令，这是一个 ruby 写的可执行脚本，代码如下：

require 'puma/cli'
cli = Puma::CLI.new ARGV
cli.run

可见，实际处理命令行参数和启动 puma 的是 Puma::CLI 类。命令行启动的时候，可以传递一些参数给 puma。参数有两种格式：短的和长的，比如-p 和 --port 都是设置监听端口。你可以在命令行把所有的 puma 参数都设置好，也可以把设置参数写在一个文件里，然后通过-C 来引用。

$ puma -b tcp://127.0.0.1:9292 -t 8:32 -w 3
$ puma -C /path/to/config

CLI 启动 puma 的具体流程见下一节。

Puma 的启动流程

这里主要讲解命令行启动 puma 的流程。启动过程分两步，首先是初始化 Puma::CLI 类，然后执行 cli.run 方法。

Puma 的 CLI 初始化

CLI 初始化的代码如下：

def initialize(argv, events=Events.stdio)
......
  @events = events
  setup_options
  generate_restart_data
  @binder = Binder.new(@events)
  @binder.import_from_env
end

主要步骤包括：初始化事件的标准输出与错误输出、设置命令行参数的缺省值、设置解析命令行参数的代码、设置重启 puma 的命令行、初始化 Binder 类。

setup_options 方法首先设置命令行参数的缺省值，比如缺省的最小和最大线程数是 0 和 16。然后初始化@parser对象，实现命令行参数的解析。解析代码也很简单，每找到一个命令行参数，就把它加入@options数组。

def setup_options
  @options = {
    :min_threads => 0,
    :max_threads => 16,
    ......
  }

  @parser = OptionParser.new do |o|
    o.on "-b", "--bind URI", "URI to bind to (tcp://, unix://, ssl://)" do |arg|
      @options[:binds] << arg
    end
  ......
end

然后是获取重启 puma 的命令行，并保存到@restart_argv中。

def generate_restart_data
  @restart_dir ||= Dir.pwd
  @original_argv = ARGV.dup
  if File.exist?($0)
    arg0 = [Gem.ruby, $0]
  else
    arg0 = [Gem.ruby, "-S", $0]
  end
  # Detect and reinject -Ilib from the command line
  lib = File.expand_path "lib"
  arg0[1,0] = ["-I", lib] if $:[0] == lib
  @restart_argv = arg0 + ARGV
end

由于 generate_restart_data 方法比较难懂，这里演示一下阅读 puma 源代码时的调试过程。首先下载 puma 的源代码并编译。

ylt~/tmp/$ git clone https://github.com/puma/puma.git
ylt~/tmp/$ cd puma
ylt~/tmp/puma$ rake

然后在文件 lib/puma/cli.rb 的 374 行设置断点，我使用的是 byebug。接着使用下面的命令启动 puma：

ylt~/tmp/puma$ ruby -I lib/ bin/puma
[371, 380] in /Users/ylt/tmp/puma/lib/puma/cli.rb
   371:         else
   372:           @restart_argv = arg0 + ARGV
   373:         end
   374:         byebug
   375:       end
=> 376:     end
   377: 
   378:     def restart_args
   379:       if cmd = @options[:restart_cmd]
   380:         cmd.split(' ') + @original_argv
(byebug) @restart_argv
["/Users/ylt/.rvm/rubies/ruby-2.1.2/bin/ruby", "-I", "/Users/ylt/tmp/puma/lib", "bin/puma"]
(byebug) $0
"bin/puma"

代码中有不懂的地方，直接在调试环境中执行代码，比如查看@restart_argv和$0到底是什么值。如果想知道 restart_argv 到底有什么用，用 grep 搜索代码目录，看看在哪个地方使用了这个变量。最终会发现只有一个地方使用了它，简化后的代码是：

def restart!
  argv = restart_args
  Dir.chdir @restart_dir
  argv += [redirects] unless RUBY_VERSION < '1.9'
  Kernel.exec(*argv)
end

也就是通过 Kernel.exec 来执行命令行来重启。

###Puma 的运行流程完成 Puma::CLI 的初始化以后，调用其 run 方法将 puma 实际运行起来，这个 run 方法是 puma 执行的主函数体。

def run
  parse_options
  set_rack_environment
  if clustered?
    @events.formatter = Events::PidFormatter.new
    @options[:logger] = @events
    @runner = Cluster.new(self)
  else
    @runner = Single.new(self)
  end
  setup_signals
  set_process_title
  @status = :run
  @runner.run
  # 这里等待runner运行结束，一般是收到了KILL类信号
  case @status
  when :halt
    log "* Stopping immediately!"
  when :run, :stop
    graceful_stop
  when :restart
    log "* Restarting..."
    @runner.before_restart
    restart!
  when :exit
    # nothing
  end
end

Puma 运行的第一步是解析命令行参数，然后设置 rack 环境。下一步判断是否运行为集群模式，如果是集群模式，初始化 Cluster 类；如果是单进程模式，初始化 Single 类。然后是设置操作系统信号的处理函数、设置 puma 进程标题。紧接着是设置 puma 主进程的状态为:run，并执行 runner 的 run 方法。run 方法进行几层的封装，最终会执行到 Server 类的 run 方法，其中的关键循环是：

while @status == :run
begin
  ios = IO.select sockets
  ...
end

此时 puma 服务器就可以接收 web 客户端的请求了，同时等待操作系统的退出信号。当收到操作系统的退出信号后，代码执行到 case @status处，这里判断信号类型来决定是停止还是重启 puma。

Puma 源代码分析－概述

ylt — Fri, 27 Feb 2015 23:32:49 +0800

2015 年春节期间，通读了 Puma 的源代码。阅读 Puma 的源码是一个愉快的技术探索过程，这里把阅读所得分享出来。

Puma 总体架构

什么是 Puma?

Puma 是一个面向 ruby 语言的并发的 Web 服务器（a modern, concurrent web server for ruby）。它的官方网站是puma.io.

什么是 Web 服务器？

一个标准的 Web 服务器遵循 HTTP 协议，接受 HTTP Request 请求，返回 HTTP Response 的响应结果。请求和响应都是字符串流的格式。如图 1 所示：

使用 curl 命令可以很方便的测试和学习 HTTP 协议。比如执行下面的 curl 命令，可以看到 http 的请求和响应。

curl  -v http://z.cn

Http 的请求由 curl 发出，curl 此时就是 Web Client。

GET / HTTP/1.1
User-Agent: curl/7.37.1
Host: z.cn
Accept: */*

然后 z.cn 的 web 服务器收到 HTTP Request 请求，并返回 HTTP Response 的响应结果，如下：

HTTP/1.1 301 Moved Permanently
Date: Thu, 26 Feb 2015 07:25:05 GMT
Location: http://www.amazon.cn/ref=z_cn?tag=zcn0e-23
Content-Length: 250
Content-Type: text/html; charset=iso-8859-1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="http://www.amazon.cn/ref=z_cn?tag=zcn0e-23">here</a>.</p>
</body></html>

Web 服务器根据 Http 请求的路径和其他头部信息来决定如何输出 Http 的响应结果。Web 服务器有三种方式处理 Http 请求：

代理到下一级的 Web 服务器；
对静态文件请求，直接读取本地文件内容并输出；
对动态请求，则通过接口调用动态程序。

对于第三种的动态请求，又有很多接口规范，比如 cgi/fastcgi, servlet, rack 等。其中 cgi/fastcgi 是语言无关的，servlet 是特定于 java 语言的，而 rack 是特定于 ruby 语言的。

Ruby/Rack Web 服务器

Rack 的官方网站是rack.github.io。支持 Rack 的 Web 服务器的架构如图 2 所示：

Rack 应用的输入是一个表示环境的 hash，输出是一个数组包括三个元素：

HTTP 响应码
HTTP 响应头的 Hash
HTTP 响应体，该响应体必须支持 each 方法调用

Rack 服务器和 Rack 应用之间通过 ruby 对象交互，Rack 服务器直接调用 Rack 应用；而 Web 服务器和 Web 客户端之间则是通过字符串流交互。

Puma 是一个支持 Ruby/Rack applications 的 Web 服务器。其它支持 Rack 规范的 Web 服务器还有 Unicorn／Thin／Passenger 等。

Puma 的源代码结构

Puma 是一个典型的 Rack 服务器。其总体目录结构与关键源代码文件如下：

├── bin   可执行脚本
│   ├── puma      启动脚本
│   ├── puma-wild
│   └── pumactl   控制脚本
├── docs 文档
├── examples  一些例子文件
├── ext   ruby的原生扩展，实现快速解析HTTP的头部
│   └── puma_http11  
├── lib
│   ├── puma
│   │   ├── app
│   │   │   └── status.rb     响应pumactl的控制请求
│   │   ├── binder.rb         启动并绑定Tcp／Unix端口
│   │   ├── cli.rb            Puma的命令行接口，解析命令行参数
│   │   ├── client.rb         代表Http请求的客户端
│   │   ├── cluster.rb            Puma的集群模式
│   │   ├── configuration.rb  Puma的配置参数
│   │   ├── control_cli.rb     命令行控制脚本的实现代码
│   │   ├── daemon_ext.rb      实现puma进程的daemon化
│   │   ├── events.rb          服务器的事件支持
│   │   ├── null_io.rb            当request没有body时rack.input的值
│   │   ├── rack_default.rb   指定缺省的rack handler
│   │   ├── rack_patch.rb     Patch CommonLogger to use after_reply
│   │   ├── reactor.rb        所有需要监听新数据的client链接，放到reactor的@sockets队列中
│   │   ├── runner.rb     启动Puma Server的基类,Single/Cluster继承它
│   │   ├── server.rb     The HTTP Server itself. Serves out a single Rack app.
│   │   ├── single.rb     Puma的单进程模式
│   │   ├── thread_pool.rb 线程池，其中是所有可执行的worker
│   ├── puma.rb
│   └── rack
│       └── handler
│           └── puma.rb       缺省的puma rack handler实现
├── test  测试代码
└── tools 进程监控脚本：init.d/upstart
    ├── jungle
    │   ├── init.d
    │   └── upstart

本系列后续部分将详细分析 Puma 如何启动、如何监听 tcp 连接，如何解析 http header，如何执行 rack app，如何响应控制命令，如何处理文件上传，如何实现集群模式，如何使用 reactor 模型处理 io 等。

Puma 中关于 Jruby 和 SSL 支持的部分本文档不会涉及。因为笔者自己都是在 MRI ruby 上跑 puma 的，没有用过 jruby 跑 puma，而且 SSL 都是交给 web 接入层比如 nginx 处理的，所以 puma 中这两个功能点的代码就不关心了。

Puma 源代码分析－启动流程 Puma 源代码分析－单进程模式 Puma 源代码分析－集群模式 Puma 源代码分析－ IO 处理 Puma 源代码分析－ http 协议解析 Puma 源代码分析－完结篇

Rails / Nginx 与 Weak Etag

ylt — Mon, 15 Dec 2014 00:15:45 +0800

Ruby-china 上有几篇讨论 Etag 的帖子，比如

要了解 Etag 的使用，推荐先看看上面的文章和讨论。但是我好像没有看到过介绍 rails 中使用 Weak Etag 的。

在讨论 Weak Etag 前，先解释一下 rails 自带的中间件 Rack::ETag 与自己写 fresh_when/is_stale 的区别。使用 Rack::ETag 能够节省网络传输时间，并不节省服务器端的计算量；而使用 fresh_when 则能节省页面渲染＋网络传输时间，复杂一些的 Rails 的页面渲染一般需要 10ms 以上，这是 fresh_when 相比 Rack::ETag 能够节省下来的。我的做法是重要的页面自己使用 fresh_when 计算 Etag，其它统统让 Rack::ETag 处理。

但是用 Rails 生成 Etag 配合 Nginx 有个坑，就是使用 Nginx 的压缩的时候，Nginx 会简单的把 Etag 去掉，理由是压缩后的内容变化了，Etag 无效了。Quakewang 的帖子中提到了这个问题，并给出了两种解决办法：1.用 Rack 中间件进行 gzip 压缩，2.修改 nginx 源代码。其实这两种方案都不能让人满意。这个坑就引出了本文的主角 Weak Etag，对 Etag 详细的说明见下面的链接：

http://en.wikipedia.org/wiki/HTTP_ETag

简单来说，Weak Etag 和 (strong) ETag 的区别在于：Etag 保证文件的内容是完全相同的，而 Weak Etag 只保证文件的内容是语义上相同的。区分 ETag 和 Weak Etag 对一些 byte by byte 的操作有影响，比如断点续传等。

Weak Etag 就是在 Etag 前面增加了两个字符 W/，比如：

"123456789" -- A strong ETag validator W/"123456789" -- A weak ETag validator

从 Nginx1.7.3 版本开始，其 gzip 模块能正确的处理 Weak Etag 了。源代码在下面两个文件中： src/http/modules/ngx_http_gzip_filter_module.c src/http/ngx_http_core_module.c

如果 response 中带 Weak Etag，那么 Nginx 的 gzip 模块不处理；如果 response 中带 strong Etag，那么 Nginx 会把它转化为 Weak Etag。

所以如果使用了 Nginx1.7.3 以后版本，让 rails 应用支持 etag 很简单。让 rails 生成的 Etag 成为 Weak Etag 即可，代码如下：

class WeakEtagMiddleware
  def initialize(app)
    @app = app
  end

  def call(env)
    # make request etags "strong"
    etag = env['HTTP_IF_NONE_MATCH']
    if etag && etag =~ /^W\//
      env['HTTP_IF_NONE_MATCH'] = etag[2..-1]
    end

    status, headers, body = @app.call(env)

    # make response etags "weak"
    etag = headers['ETag']
    if etag && etag !~ /^W\//
      headers['ETag'] = "W/#{etag}"
    end

    [status, headers, body]
  end
end

也可以使用 gem 'rails_weak_etags', 代码拷贝自 http://stackoverflow.com/questions/18693718/weak-etags-in-rails

此外，Rack::ETag 在 1.6.0.beta2 以后，默认也生成 Weak Etag。 https://github.com/rack/rack/commit/12528d4567d8e6c1c7e9422fee6cd8b43c4389bf 如果你使用的 Rails 版本足够新，那么不需要做任何事情就能正确处理 Etag 了。我目前还是使用的 Rack 1.5 的版本，所以还是需要上面的解决方案。

[杭州] 脸脸招聘 Web/Ruby 团队 Leader

ylt — Tue, 14 Oct 2014 11:50:16 +0800

脸脸是全球首款基于场所的社交 APP。当人们在同一个地点，在脸脸中就可以进入同一个场所，然后就会有一些好玩的事情发生。比如我们国庆节的时候在杭州西溪印象城搞了一场哆啦 A 梦的活动就很成功。脸脸的目标是成为所有线下场所的首选 APP。

国庆期间有 30 万人参与了杭州西溪印象城的哆啦 A 梦的活动。

整点抢答时刻，人潮涌动。

通过猜图活动，在脸脸中拿到的优惠券。在印象城这种综合性消费场所，各种吃喝玩乐商家很多，即时收到的优惠券对我接下来去那个店消费有很大的影响力。因为是近场营销，转换率非常高。

介绍一下脸脸现在的技术栈：数据库层混合使用 Mongdb、Mysql、Redis，其中地点数据／Json 数据等保存在 Mongodb 中，需要交易与事务支持的数据保存在 Mysql 中、社交类数据如好友关系和赞等数据保存在 Redis 中。以前还尝试过 Riak／Cassandra／Hadoop 等，最后发现目前的阶段不合适。

使用的开发语言主要是 Ruby，大部分的 Web 应用都是用 Rails 开发的，应用服务器是 Puma，后台任务有 Resque/Sidekiq。除了 Ruby 外还使用了 Erlang／Nodejs／Php，其中 Erlang 用于即时通讯、Nodejs 用于网络代理、Php 则用在接入国内各种第三方 Api。Web 接入使用的是 Nginx，进程监控用的是 God。

我们刚刚敲定了 A 轮的风投，正在扩充技术团队，现需要一位 Web／Ruby 团队 Leader。

岗位要求

三年以上的 Web 应用开发经验，一年以上的技术团队管理经验，有带队使用 Rails 成功开发项目的经验
熟悉 Ruby 编程语言和 Rails 开发框架，熟悉一种常见的 Sql 和 Nosql 数据库
良好的沟通能力和团队合作能力，以及独立调研新技术的能力

岗位职责

带领团队进行 Web 应用和项目的开发，对研发全过程进行管理。
负责 Web／Ruby 技术栈关键技术研究及技术预研，确定系统总体架构、业务架构、数据架构。
需要有编码能力，需要编写系统核心部分的代码以及解决技术难题。

待遇

创业公司条件受限，但是我们会提供能力范围内的最好的待遇，基本月薪 15k - 25k，根据个人能力而定，提供期权。

加分项：

有 nodejs 或者 erlang 的编程经验
在 github 上有 star 多于 10 个开源项目
有 10 人以上的技术团队的管理经验

简历发到 yuan_xin_yu@hotmail.com 邮箱，标题请写：应聘 Ruby 团队 Leader 也可以电话联系：15868870052

[杭州] 脸脸招聘前端程序员／Erlang 程序员／UI 设计师

ylt — Wed, 15 Jan 2014 20:06:56 +0800

脸脸是一个创业公司，半年前在 RubyChina 上发贴招到了两个 ruby 程序员，上次招聘的详情见http://ruby-china.org/topics/10929。Ruby 程序员我们常年招聘。

脸脸的发展非常快速，急需其它方向的靠谱的人加盟。这次招聘的职位包括前端程序员／Erlang 程序员／UI 设计师各一名。

应聘者要求有较强的专业技能，具体的招聘要求就不列了。

如果你看过精益创业、乔布斯传、浪潮之巅，如果你用 github、mac、开源软件，如果你是一个自我要求高且希望有所成就的人，那么你就是我们要找的人。

脸脸的介绍可以参考：https://itunes.apple.com/cn/app/lianlian/id577710538

薪资待遇：创业公司薪资不高，目前能提供月薪 6k - 16k，根据个人能力而定。期权也会有，脸脸近期会进行一次较大的 A 轮融资。

工作地点：杭州市西湖区

如果你觉得有兴趣，欢迎发 email：yuan_xin_yu@hotmail.com 和我联系。

[杭州] 脸脸招聘 Ruby 程序员 / 架构师

ylt — Sun, 12 May 2013 23:22:31 +0800

脸脸是一个创业公司，正在开发一款同名的移动设备上的现场交友应用，目前 IOS 正式版已经上线，下载地址http://www.dface.cn。

脸脸的服务器端基于 Linux/Ruby/Mongodb 等开源技术开发，我们希望找同样喜欢开源技术、喜欢写代码的程序员／架构师加盟。

岗位要求：除了热爱写代码、有自己的开源项目外，没有学位／户口／性别／精通 XXX 等任何其它的要求。

薪资待遇：创业公司薪资不高，目前能提供月薪 8k - 16k，根据个人能力而定。