the_metal
DESCRIPTION:
A spike for researching Rack 2.0
FEATURES/PROBLEMS:
Totally experimental. It's just a spike.
SYNOPSIS:
An app without any middleware:
gem 'the_metal', github: 'tenderlove/the_metal'
require 'the_metal/puma'
TheMetal.create_server(->(req, res) {
res.write_head 200, 'Content-Type' => 'text/plain'
res.write "Hello World\n"
res.finish
}).listen 9292, '0.0.0.0'
You can use a class too:
class Application
def call req, res
res.write_head 200, 'Content-Type' => 'text/plain'
res.write "Hello World\n"
res.finish
end
end
require 'the_metal/puma'
server = TheMetal.create_server Application.new
server.listen 9292, '0.0.0.0'
An app that checks out a database connection when the request starts and checks it back in when the response is finished:
require 'the_metal'
class Application
def call req, res
res.write_head 200, 'Content-Type' => 'text/plain'
res.write "Hello World\n"
res.finish
end
end
class DBEvents
def start_app app
puts "ensure database connection"
end
def start_request req, res
puts "-> checkout connection"
end
def finish_request req, res
puts "<- checkin connection"
end
end
require 'the_metal/puma'
app = TheMetal.build_app [DBEvents.new], [], Application.new
server = TheMetal.create_server app
server.listen 9292, '0.0.0.0'
Server side output:
ensure database connection
-> checkout connection
<- checkin connection
An app that buffers responses so it can calculate a Content-Length
header:
require 'the_metal'
require 'the_metal/response'
class Application
def call req, res
res.write_head 200, 'Content-Type' => 'text/plain'
res.write "Hello World\n"
res.finish
end
end
class ContentLength
class BufferedResponse < DelegateClass(TheMetal::Response)
def initialize delegate
super
@headers = {}
@body = []
end
def write_head status, headers
self.status = status
@headers = headers
end
def write chunk
@body << chunk
end
def finish
body = @body.join
size = body.bytesize
@headers['Content-Length'] = size
__getobj__.write_head status, @headers
__getobj__.write body
super
end
end
def filter req, res, chain
puts "filtering"
chain.next req, BufferedResponse.new(res)
end
end
require 'the_metal/puma'
app = TheMetal.build_app [], [ContentLength.new], Application.new
server = TheMetal.create_server app
server.listen 9292, '0.0.0.0'
IDEAS:
Middleware
We should separate middleware from the server itself. In other words,
build_app
should probably be a separate Gem, and we can make a nicer API
for it than the above examples.
I think Rack middleware should be out of scope for Rack 2.0. This is
analogous to the Node.JS / Connect relationship. We should develop a
middleware handler separately from the webserver interface. The build_app
middleware API implemented here is just a suggestion and an experiment to
demonstrate how middleware could work with this API. I think Rack 2.0 should
only handle the first example.
Webservers
Webserver should supply a request and response object to the handler. Rack 2.0 will define the API on the request and response object, but we should keep it to a minimum. Rack 2.0 should implement request and response objects that webserver implementers can reuse -- we shouldn't have code for writing headers to a socket duplicated across many webserver implementations.
Application code should be executed immediately after the request headers have been read in. The request object should have an IO where post bodies can be ready. The IO is not rewindable.
The response object should have an output IO. The output IO doesn't have to be the same as the input IO. This is entirely up to the webserver implementer.
Tests
So far, the ideas I've laid out are sort of vague, and I've not been very specific about the exact behavior. To address this, I think we should develop a test suite that web server implementors can run to ensure that all webservers behave similarly. Think RubySpec, but for Ruby webservers. I've demonstrated that with Unicorn, Puma, and WEBRick in the tests for this project.
Finally
This is a spike. It is extremely experimental at this point, but it puts most of my thoughts to code. My overall idea is:
- Applications should be dealing with streams
- Request / Response objects abstract applications from specific implementations
- A middleware framework should not be defined by Rack 2.0.
- Test should ensure webserver compatibility
If you have ideas for changes, please open a ticket or send a pull request. Let's make the HTTP landscape for Ruby even more amazing!
LICENSE:
(The MIT License)
Copyright (c) 2014 Aaron Patterson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.