midori.rb 0.4.3

data/lib/midori/server.rb

@@ -0,0 +1,106 @@
+##
+# Logic to EventMachine TCP Server, running inside +Midori::Connection+
+module Midori::Server
+  # @!attribute request
+  #   @return [Midori::Request] raw request
+  # @!attribute api
+  #   @return [Class] inherited from Midori::API
+  # @!attribute websocket
+  #   @return [Midori::WebSocket] defined websocket instance
+  # @!attribute eventsource
+  #   @return [Midori::EventSource] defined eventsource instance
+  attr_accessor :request, :api, :websocket, :eventsource
+
+  # Define server behaviour
+  # @param [Class] api inherited from Midori::API
+  # @param [Logger] logger global logger
+  def server_initialize(api, logger)
+    @api = api
+    @logger = logger
+    @request = Midori::Request.new
+    @websocket = Midori::WebSocket.new(self)
+    @eventsource = Midori::EventSource.new(self)
+  end
+
+  # Logic of receiving data
+  # @param [String] monitor the socket able to read
+  def receive_data(monitor)
+    lambda do
+      async_fiber(Fiber.new do
+        begin
+          _sock_domain, remote_port, _remote_hostname, remote_ip = monitor.io.peeraddr
+          port, ip = remote_port, remote_ip
+          @request.ip = ip
+          @request.port = port
+          data = monitor.io.read_nonblock(16_384)
+          if @request.parsed? && @request.body_parsed?
+            websocket_request(StringIO.new(data))
+          else
+            @request.parse(data)
+            receive_new_request if @request.parsed && @request.body_parsed?
+          end
+        rescue => e
+          close_connection
+          @logger.warn "#{@request.ip} - - #{e.class} #{e.backtrace.join("\n")}".yellow
+        end
+      end)
+    end.call
+  end
+
+  # Logic of receiving new request
+  def receive_new_request
+    begin
+      start_time = Time.now
+      @response = @api.receive(request, self)
+      now_time = Time.now
+      @logger.info "#{@request.ip} - - \"#{@request.method} #{@request.path} HTTP/#{@request.protocol.join('.')}\" #{@response.status} #{sprintf("%.6f", now_time.to_f - start_time.to_f)}".green
+      call_event(:open) if @request.websocket?
+    rescue Midori::Exception::NotFound => e
+      @response = Midori::Sandbox.capture(e)
+    rescue => e
+      @response = Midori::Sandbox.capture(e)
+      @logger.error e.inspect.red
+      @logger.warn e.backtrace.join("\n").yellow
+    end
+    unless @request.websocket? || @request.eventsource?
+      send_data @response
+      close_connection_after_writing
+    end
+  end
+
+  # Logic of receiving WebSocket request
+  # @param [StringIO] data raw data
+  def websocket_request(data)
+    @websocket.decode(data)
+    case @websocket.opcode
+    when 0x1, 0x2
+      call_event(:message, [@websocket.msg])
+    when 0x9
+      @websocket.pong(@websocket.msg)
+      call_event(:ping)
+    when 0xA
+      call_event(:pong)
+    end
+  rescue Midori::Exception::FrameEnd => _e
+    call_event(:close)
+    send_data "\b" # Opcode 0x8
+    close_connection_after_writing
+  rescue Midori::Exception::PingPongSizeTooLarge => e
+    @logger.warn e.inspect.yellow
+    call_event(:error) # Too large ping request
+    send_data "\b" # Opcode 0x8
+    close_connection_after_writing
+  rescue => e
+    call_event(:error)
+    @logger.error e.inspect.red
+    @logger.warn e.backtrace.join("\n").yellow
+    close_connection_after_writing
+  end
+
+  # To call a websocket event if it exist
+  # @param [Symbol] event event name
+  # @param [Array] args arg list
+  def call_event(event, args = [])
+    -> { @websocket.instance_exec(*args, &@websocket.events[event]) }.call unless @websocket.events[event].nil?
+  end
+end

data/lib/midori/version.rb

@@ -0,0 +1,5 @@
+# Midori Module
+module Midori
+  # Current Version Code
+  VERSION = '0.4.3'.freeze
+end

data/lib/midori/websocket.rb

@@ -0,0 +1,105 @@
+##
+# This class provides methods for WebSocket connection instance.
+# @attr [Array<Integer>, String] msg message send from client
+# @attr [Integer] opcode operation code of WebSocket
+# @attr [Hash] events response for different event
+# @attr [Midori::Connection] connection raw EventMachine connection
+# @attr [Midori::Request] request raw request
+class Midori::WebSocket
+  attr_accessor :msg, :opcode, :events, :connection, :request
+
+  # Init a WebSocket instance with a connection
+  # @param [Midori::Connection] connection raw EventMachine connection
+  def initialize(connection)
+    @events = {}
+    @connection = connection
+  end
+
+  # Decode raw data send from client
+  # @param [StringIO] data raw data
+  def decode(data)
+    # Fin and Opcode
+    byte_tmp = data.getbyte
+    fin = byte_tmp & 0b10000000
+    @opcode = byte_tmp & 0b00001111
+    # NOT Support Multiple Fragments
+    raise Midori::Exception::ContinuousFrame unless fin
+    raise Midori::Exception::OpCodeError unless [0x1, 0x2, 0x8, 0x9, 0xA].include? opcode
+    close if @opcode == 0x8 # Close Frame
+    # return if @opcode == 0x9 || @opcode == 0xA # Ping Pong
+    decode_mask(data)
+  end
+
+  # Decode masked message send from client
+  # @param [StringIO] data raw data
+  def decode_mask(data)
+    # Mask
+    byte_tmp = data.getbyte
+    is_masked = byte_tmp & 0b10000000
+    raise Midori::Exception::NotMasked unless is_masked == 128
+    # Payload
+    payload = byte_tmp & 0b01111111
+    mask = Array.new(4) { data.getbyte }
+    # Message
+    masked_msg = Array.new(payload) { data.getbyte }
+    @msg = self.mask(masked_msg, mask)
+    @msg = @msg.pack('C*').force_encoding('utf-8') if [0x1, 0x9, 0xA].include?opcode
+    # For debug
+    #  data.rewind
+    #  data.bytes {|byte| puts byte.to_s(16)}
+  end
+
+  # API definition for events
+  # @param [Symbol] event event name(open, message, close, ping, pong)
+  # @yield what to do after event matched
+  # @example
+  #   websocket '/websocket' do |ws|
+  #     ws.on :message do |msg|
+  #       puts msg
+  #     end
+  #   end
+  def on(event, &block) # open, message, close, ping, pong
+    @events[event] = block
+  end
+
+  # Send data
+  # @param [Array<Integer>, String] msg data to send
+  def send(msg)
+    output = []
+    if msg.is_a?String
+      output << 0b10000001 << msg.size << msg
+      @connection.send_data(output.pack("CCA#{msg.size}"))
+    elsif msg.is_a?Array
+      output << 0b10000010 << msg.size
+      output.concat msg
+      @connection.send_data(output.pack('C*'))
+    else
+      raise Midori::Exception::OpCodeError
+    end
+  end
+
+  # Send a Ping request
+  # @param [String] str string to send
+  def ping(str)
+    heartbeat(0b10001001, str)
+  end
+
+  # Send a Pong request
+  # @param [String] str string to send
+  def pong(str)
+    heartbeat(0b10001010, str)
+  end
+
+  # Ancestor of ping pong
+  # @param [Integer] method opcode
+  # @param [String] str string to send
+  def heartbeat(method, str)
+      raise Midori::Exception::PingPongSizeTooLarge if str.size > 125
+      @connection.send_data [method, str.size, str].pack("CCA#{str.size}")
+  end
+
+  # Close a websocket connection
+  def close
+    raise Midori::Exception::FrameEnd
+  end
+end

data/lib/midori.rb

@@ -0,0 +1,37 @@
+require 'cgi'
+require 'digest/sha1'
+require 'stringio'
+require 'fiber'
+require 'logger'
+require 'http/parser'
+require 'mustermann'
+require 'murasaki'
+require 'socket'
+
+require_relative 'midori_ext'
+require_relative 'midori/core_ext/configurable'
+require_relative 'midori/core_ext/string'
+require_relative 'midori/core_ext/define_class'
+require_relative 'midori/core_ext/proc'
+
+require_relative 'midori/version'
+
+require_relative 'midori/const'
+require_relative 'midori/exception'
+require_relative 'midori/env'
+require_relative 'midori/clean_room'
+require_relative 'midori/server'
+require_relative 'midori/connection'
+require_relative 'midori/request'
+require_relative 'midori/response'
+require_relative 'midori/api'
+require_relative 'midori/api_engine'
+require_relative 'midori/route'
+require_relative 'midori/sandbox'
+require_relative 'midori/websocket'
+require_relative 'midori/eventsource'
+require_relative 'midori/middleware'
+require_relative 'midori/configure'
+require_relative 'midori/runner'
+require_relative 'midori/logger'
+

data/midori.sublime-project

@@ -0,0 +1,16 @@
+{
+  "folders":
+  [
+    {
+      "path": ".",
+      "folder_exclude_patterns": [".resources", "coverage"],
+      "file_exclude_patterns": ["midori-*.gem","*.sublime-workspace","logo.png",".DS_Store","CODE_OF_CONDUCT.md","CONTRIBUTING.md"]
+    }
+  ],
+	"settings":
+	{
+		"tab_size": 2,
+		"translate_tabs_to_spaces": true,
+		"trim_trailing_white_space_on_save": true
+	}
+}

data/tutorial/README.md

@@ -0,0 +1,11 @@
+# Introduction
+
+## What is midori?
+
+Midori (pronounced /miːdɒliː/) is a **Ruby web framework** for building APIs, web pages and realtime web services. Midori is designed to provide **non-blocking** I/O operations without **callback hells** on web development. The core library is focused on network I/Os, and gives a very easy DSL to pick up and converting existed projects on. On the other hand, midori also officially provides extension libraries that could deal with file, database, cache, network requests and other I/O operations without blocking.
+
+If you want to know how midori compares to other libraries/frameworks, checkout out the [Comparison with Other Frameworks](meta/comparison_with_other_frameworks.md)
+
+## Note
+
+The official guide assumes intermediate level knowledge of Ruby and backend development. If you are totally new , it might not be the best idea to jump right into a framework as your first step - grasp the basics then come back! Prior experience with other frameworks like Rails helps, but is not required.

data/tutorial/SUMMARY.md

@@ -0,0 +1,28 @@
+# Summary
+
+## Essentials
+
+* [Introduction](README.md)
+* [Installation](essentials/installation.md)
+* [Getting Started](essentials/getting_started.md)
+* [Routing](essentials/routing.md)
+* [Request Handling](essentials/request_handling.md)
+* [Runner](essentials/runner.md)
+* [Middlewares](essentials/middlewares.md)
+* [Extensions](essentials/extensions.md)
+
+
+## Advanced
+
+- [Error Handling](advanced/error_handling.md)
+- [Request-Eval-Response Loop](advanced/rerl.md)
+- [Custom Extensions](advanced/custom_extensions.md)
+- [Scaling Project](advanced/scaling_project.md)
+- [Unit Testing](advanced/unit_testing.md)
+- [Deploying for Production](advanced/deploying_for_production.md)
+
+## Meta
+
+- [Comparison with Other Frameworks](meta/comparison_with_other_frameworks.md)
+- [Next Steps](meta/next_steps.md)
+- [Join the Midori Community](meta/join_the_midori_community.md)

data/tutorial/essentials/extensions.md

@@ -0,0 +1,31 @@
+# Extensions
+
+Extensions are rubygems that could combine other gems with midori through meta-programming.
+There's a set of officially supported midori extensions called `midori-contrib`.
+This contains gems commonly used like Database ORM, Redis Driver, Redis ORM, HTTP Driver, etc.
+
+To include it inside your project, be sure to get the original gem installed without require it.
+Then include specific parts of `midori-contrib` to make it work.
+
+For example:
+
+`Gemfile`
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'bundler', '~> 1.0'
+gem 'rake', '~> 12.0'
+
+gem 'hiredis', '~> 0.6.0', require: false
+gem 'ohm', '~> 3.0'
+gem 'sequel', '~> 5.0', require: false
+gem 'mysql2', '~> 0.4', require: false
+
+gem 'em-midori', '~> 0.4.3', require: 'midori'
+gem 'midori-contrib', '~> 0.1.0', require: %w(
+    midori-contrib
+    midori-contrib/sequel/mysql2
+    midori-contrib/redic
+  )
+```

data/tutorial/essentials/getting_started.md

@@ -0,0 +1,27 @@
+# Getting Started
+
+## Hello Midori
+
+midori is a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for web and API development in Ruby  with minimal effort:
+
+```ruby
+# hello_midori.rb
+require 'midori'
+
+class HelloWorldAPI < Midori::API
+  get '/' do
+    'Ohayou Midori'
+  end
+end
+
+Midori::Runner.new(HelloWorldAPI).start
+```
+
+Run with
+
+```
+$ ruby hello_midori.rb
+```
+
+View at: http://127.0.0.1:8080 with your browser, if you see a page showing: **Ohayou Midori**. You've made your first application with midori.
+

data/tutorial/essentials/installation.md

@@ -0,0 +1,93 @@
+# Installation
+
+## Requirements
+
+Open up a command line prompt. Any commands prefaced with a dollar sign `$` should be run in the command line. Verify that you have a current version of Ruby installed:
+
+```
+ $ ruby -v
+ ruby 2.4.1p111
+```
+
+Generally, midori supports the following ruby interpreters:
+
+- Ruby (MRI) **>= 2.2.6**
+
+ For every version released, it would be tested and **officially ensured** in the following environments:
+
+- Ruby (MRI)
+  - 2.2.8
+  - 2.3.5
+  - 2.4.2
+
+**Note: **
+
+- **For JRuby users, due to some C extensions used in midori, it is still unable to run on the current version of JRuby.**
+- **For macOS users, you may meet performance problem due to the issue of [nio4r](https://github.com/socketry/nio4r/issues/125). Very few people would use macOS in production, so this issue may not affect much. We would still be working hard on fixing it, but the issue wouldn't be a high priority one.**
+
+It's hard to say that if it is possible for running on other ruby implementations like Rubinius or RubyMotion, if you're in favor of supporting more ruby implementations, you could open a ticket [here](https://github.com/heckpsi-lab/em-midori/issues), and we are glad to discuss it.
+
+## Install with RubyGems
+
+```
+$ gem install em-midori
+Successfully installed em-midori-0.4.3
+1 gem installed
+```
+
+To test whether it has installed properly, run:
+
+```
+$ ruby -r "midori" -e "class A < Midori::API;end;Midori::Runner.new(A).start"
+```
+
+If you see the following message, then everything now works fine.
+
+```
+Midori 0.4.3 is now running on 127.0.0.1:8080
+```
+
+## Use Bundler
+
+Example `Gemfile` of basic usage as following:
+
+```ruby
+source 'https://rubygems.org'
+gem 'bundler', '~> 1.0'
+gem 'em-midori', '~> 0.4', require: 'midori'
+```
+
+and then running:
+
+```
+$ bundle install
+```
+
+You could use
+
+```ruby
+require 'bundler'
+Bundler.require
+```
+
+in your entrance ruby file.
+
+To include built-in extensions of midori you could make your `Gemfile` like:
+
+```ruby
+source 'https://rubygems.org'
+gem 'bundler', '~> 1.0'
+gem 'em-midori', '~> 0.4', require: 'midori'
+gem 'midori-contrib', '~> 0.0.1', require: %w'midori-contrib/file midori-contrib/sequel/mysql2'
+```
+
+Using bunlder could make dependency management much easier, which helps a lot in scaling project. To learn more about bundler, you could see docs [here](http://bundler.io/docs.html). 
+
+## For Developers in China
+
+You may probably meet problems with rubygems due to unstable overseas internet connection issues in China. The most popular way to solve it is to use mirror provided by [RubyChina](https://gems.ruby-china.org/) or [TUNA](https://mirror.tuna.tsinghua.edu.cn/help/rubygems/) as your gem source. This may have some side effects in development, because there's a few minutes' delay in receiving gem updates.
+
+Alternatively, you could use proxy to connect to the main repository directly to avoid the delay problem. But using proxy is a little too complex in production environment.
+
+Choose the solution better fits your requirements. Mixing the solutions like using proxy in development and using mirror in production is also a good choice.
+

data/tutorial/essentials/middlewares.md

@@ -0,0 +1,88 @@
+# Middlewares
+
+Middlewares are very exciting features midori support.
+As it has been implemented for lots of web frameworks.
+Middlewares from midori behaves very different from other frameworks, which greatly helps reducing complexity and improving performance in scaling projects.
+
+## Basic Usage
+
+To begin with, inheritate the `Midori::Middleware` class. Here's an example:
+
+```ruby
+class JSONMiddleware < Midori::Middleware
+  def before(request)
+    request.body = JSON.parse(request.body) unless request.body == ''
+    request
+  end
+
+  def after(_request, response)
+    response.header['Content-Type'] = 'application/json'
+    response.body = response.body.to_json
+    response
+  end
+end
+```
+
+To use middleware inside router, there're two possible ways.
+One is through `use` method, which would affect all routes in the current scope.
+The other is through `filter` method, which would affect the following route definition only.
+
+Here are some examples.
+
+```ruby
+class API < Midori::API
+  use AMiddleware
+
+  filter BMiddleware
+  get '/' do
+    # Both AMiddleware and BMiddleware works here.
+    'Hello'
+  end
+
+  get '/a' do
+    # Only AMiddleware is involved here.
+    'World'
+  end
+end
+```
+
+## Stack-less Design
+
+For rack users, middlewares are always considered as parts of stack.
+Deep stacks may cause several performance issues in Ruby, including increasing cost when context switching, thread switching and process forking, etc.
+For frameworks like Rails, it defaulty contains lots of middlewares which enlarge this problem.
+
+In midori, middlewares are no longer stack-based.
+It uses a loop-based system to run middleware code.
+This makes using of middlewares with less side effects.
+
+## Early Exit Feature
+
+Early exit feature is also supported in midori without stack.
+To make it happen, just respond an `Midori::Response` object during request processing.
+Here's an example for CORS middleware using early exit feature.
+
+```ruby
+class CorsMiddleware < Midori::Middleware
+  def before(request)
+    if request.method == :OPTIONS
+      # PREFLIGHT
+      return Midori::Response.new(
+        header: {
+          'Access-Control-Allow-Origin': request.header['Origin'],
+          'Access-Control-Request-Headers': 'Token',
+          'Access-Control-Allow-Headers': 'Token',
+          'Access-Control-Allow-Methods': 'OPTIONS, POST, PUT, DELETE'
+        }
+      )
+    else
+      request
+    end
+  end
+
+  def after(request, response)
+    response.header['Access-Control-Allow-Origin'] = request.header['Origin']
+    response
+  end
+end
+```

data/tutorial/essentials/request_handling.md

@@ -0,0 +1,74 @@
+# Request Handling
+
+## Accessing the request object
+
+The incoming request object can be accessed from request level (filter, routes, error handlers) through the `request` method:
+
+```ruby
+class ExampleAPI < Midori::API
+  get '/' do
+    request.ip           # '127.0.0.1' client ip address
+    request.port         # '8080' client port
+    request.method       # 'GET'
+    request.path         # '/'
+    request.query_string # ''
+    request.query_params # {} query params, parsed from query string
+    request.header       # {} request header
+    request.body         # request body sent by the client
+    request.params       # {} params matched in router
+    request.cookie       # {} cookie parsed from header
+  end
+end
+```
+
+**Note (for sinatra users): **The `request.body` in modori is a `String` object but not a `StringIO` object.
+
+## Construct the response object
+
+Midori accepts the return value of the block as the response body by default.
+
+You could edit variable `status` and `header` to construct things other than body.
+
+You could also return a `Midori::Response` object as your response, which could override everything.
+
+```ruby
+class ExampleAPI < Midori::API
+  get '/case_0' do
+    'Hello'
+    # HTTP/1.1 200 OK
+    # Server: Midori/1.0
+    #
+    # Hello
+  end
+  
+  get '/case_1' do
+    @status = 418
+    "I\'m a teapot"
+    # HTTP/1.1 418 I'm a teapot
+    # Server: Midori/1.0
+    #
+    # I'm a teapot
+  end
+  
+  get '/case_2' do
+    @header['Example-Header'] = 'Example-Value'
+    'Hello'
+    # HTTP/1.1 200 OK
+    # Server: Midori/1.0
+    # Example-Header: Example-Value
+    #
+    # Hello
+  end
+  
+  get '/case_3' do
+    @status = 202
+    @header['Example-Header'] = 'Example-Value'
+    Midori::Response.new(status: 200, header: {}, body: 'Hello') # Overrides everything else
+    # HTTP/1.1 200 OK
+    # Server: Midori/1.0
+    #
+    # Hello
+  end
+end
+```
+