Puma 服务器处理包含特殊字符的查询参数问题解析

问题背景

在使用 Puma 作为 Ruby 应用服务器时，开发者可能会遇到一个特殊问题：当 HTTP 请求的查询参数中包含尖括号（< 或 >）时，Puma 会抛出 Puma::HttpParserError 异常。这种情况常见于处理电子邮件地址的场景，例如用户提交类似 ?email=[e-mail]> 的查询参数。

技术分析

URI 规范要求

根据 RFC 3986 规范，URI 中的查询参数部分（query string）只能包含特定字符集：

• 未保留字符（unreserved）：字母、数字、连字符、点、下划线、波浪线
• 保留字符（reserved）：特定分隔符
• 百分号编码字符（pct-encoded）

尖括号 > 和 < 不属于上述任何一类，因此在 URI 中属于非法字符，必须进行百分号编码（> 编码为 %3E，< 编码为 %3C）。

Puma 的处理机制

Puma 6.4.0 版本后对错误处理机制进行了改进（PR #3094），现在对于 HttpParserError 会调用 lowlevel_error_handler。如果没有自定义的错误处理器，Puma 会默认返回 400 Bad Request 响应。

解决方案

客户端解决方案

正确的做法是在客户端对特殊字符进行编码：

# 错误示例
curl "http://localhost:3000/?param=>"

# 正确示例（手动编码）
curl "http://localhost:3000/?param=%3E"

# 或者让工具自动编码
curl --get --data-urlencode "param=>" http://localhost:3000/

服务器端处理

如果需要自定义错误响应，可以在 Puma 配置中使用 lowlevel_error_handler：

lowlevel_error_handler do |error, env|
  if error.is_a?(Puma::HttpParserError)
    [400, {}, ["Invalid request parameters"]]
  else
    [500, {}, ["Internal server error"]]
  end
end

最佳实践建议

1. 客户端编码：始终确保客户端对特殊字符进行正确编码
2. 服务器验证：在应用层添加参数验证逻辑
3. 错误处理：根据业务需求定制 Puma 的错误处理器
4. 日志记录：记录详细的错误信息以便排查问题

总结

Puma 对非法 URI 字符的严格处理符合 HTTP 规范要求。开发者应该理解并遵循 URI 编码规范，同时在必要时通过适当的配置来处理非法请求。对于电子邮件处理等特殊场景，建议在应用层添加预处理逻辑，确保数据的规范性。