jellyfish 0.9.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9698c593098db6a1123491fae8d2d4777697dfd
-  data.tar.gz: 033cb54f5d56f48f32bc0e44cad8feb573ec6bdb
+  metadata.gz: 8cdc77d2745d750685951db77f69943a70cb6f22
+  data.tar.gz: b16b5fb680ff9cf0102b5cb32a79f0d3f6f6ccec
 SHA512:
-  metadata.gz: 62d9b38427f883c2fd1c6a6c7725693e4a4e7bf346211d58de25b9a9fc1d1e6987bf62c27ba3101f443383e3d29bbb0b063a160b6c2818407003d5a6616bee9b
-  data.tar.gz: 9918c2af70dcfa60c35ccfae7f4d506d58c582d33cb85e7d96cdd1aa89954ec592efb007eb2a6d0b5511471128208e12521292779d10054208b8dac065d02601
+  metadata.gz: 67e8a8e8ca2ccfa92e74a19f75a15ab2fd7722bd28be1370a61dec0a304b96700f93977d5db330c3fedd4f3f61a960d1c48b8ee93863aca4b7589bbdefa59003
+  data.tar.gz: efbd49c456bb91e07f1a201c7d7399234d17c44fee34073e010724307b504eaf37662a1c19666e6f8efeb4687ba37048402072c9e3a28698dcc72b07548d3b47

data/.gitignore

@@ -1,2 +1 @@
-pkg
-*.rbc
+/pkg/

data/.travis.yml

@@ -1,11 +1,9 @@
 before_install: 'git submodule update --init'
 script: 'ruby -r bundler/setup -S rake test'
 
-env:
-  - 'RBXOPT=-X19'
-
 rvm:
   - 1.9.3
   - 2.0.0
-  - rbx-head
-  - jruby-head
+  - ruby
+  - rbx
+  - jruby

data/CHANGES.md

@@ -1,5 +1,23 @@
 # CHANGES
 
+## Jellyfish 1.0.0 -- 2014-03-17
+
+### Incompatible changes
+
+* Renamed `forward` to `cascade` to better aligned with Rack.
+
+### Enhancements for Jellyfish core
+
+* Introduced `log` and `log_error` for for controllers.
+* Introduced `not_found` to trigger 404 response.
+* Now we separate the idea of 404 and cascade. Use `not_found` for 404
+  responses, and `cascade` for forwarding requests.
+
+### Other enhancements
+
+* Now we have Jellyfish::Swagger to generate Swagger documentation.
+  Read README.md for more detail or checkout config.ru for a full example.
+
 ## Jellyfish 0.9.2 -- 2013-09-26
 
 * Do not rescue Exception since we don't really want to rescue something

data/Gemfile

@@ -1,4 +1,13 @@
 
-source 'http://rubygems.org'
+source 'https://rubygems.org'
+
 gemspec
+
 gem 'rake'
+gem 'bacon'
+gem 'muack'
+gem 'rack'
+
+platform :rbx do
+  gem 'rubysl-singleton' # used in rake
+end

data/README.md

@@ -17,13 +17,13 @@ For Rack applications or Rack middlewares. Around 250 lines of code.
 
 ## DESIGN:
 
-* Learn the HTTP way instead of using some pointless helpers
-* Learn the Rack way instead of wrapping Rack functionalities, again
-* Learn regular expression for routes instead of custom syntax
-* Embrace simplicity over convenience
-* Don't make things complicated only for _some_ convenience, but
+* Learn the HTTP way instead of using some pointless helpers.
+* Learn the Rack way instead of wrapping around Rack functionalities.
+* Learn regular expression for routes instead of custom syntax.
+* Embrace simplicity over convenience.
+* Don't make things complicated only for _some_ convenience, but for
   _great_ convenience, or simply stay simple for simplicity.
-* More features are added as extensions
+* More features are added as extensions.
 
 ## FEATURES:
 
@@ -31,7 +31,7 @@ For Rack applications or Rack middlewares. Around 250 lines of code.
 * Simple
 * Modular
 * No templates (You could use [tilt](https://github.com/rtomayko/tilt))
-* No ORM
+* No ORM (You could use [sequel](http://sequel.jeremyevans.net/))
 * No `dup` in `call`
 * Regular expression routes, e.g. `get %r{^/(?<id>\d+)$}`
 * String routes, e.g. `get '/'`
@@ -45,7 +45,7 @@ Because Sinatra is too complex and inconsistent for me.
 
 ## REQUIREMENTS:
 
-* Tested with MRI (official CRuby) 1.9.3, 2.0.0, Rubinius and JRuby.
+* Tested with MRI (official CRuby), Rubinius and JRuby.
 
 ## INSTALLATION:
 
@@ -53,9 +53,9 @@ Because Sinatra is too complex and inconsistent for me.
 
 ## SYNOPSIS:
 
-You could also take a look at [Saya][] as an example Jellyfish application.
-
-[Saya]: https://github.com/godfat/saya
+You could also take a look at [config.ru][] as an example, which also uses
+[Swagger](https://helloreverb.com/developers/swagger) to generate API
+documentation.
 
 ### Hello Jellyfish, your lovely config.ru
 
@@ -230,7 +230,7 @@ body = case RUBY_ENGINE
        when 'jruby'
          "No one hears you: (eval):9:in `Tank'\n"
        when 'rbx'
-         "No one hears you: kernel/delta/kernel.rb:81:in `yell (method_missing)'\n"
+         "No one hears you: kernel/delta/kernel.rb:78:in `yell (method_missing)'\n"
        else
          "No one hears you: (eval):9:in `block in <class:Tank>'\n"
        end
@@ -239,6 +239,29 @@ body = case RUBY_ENGINE
  [body]]
 -->
 
+### Custom error 404 handler
+
+``` ruby
+require 'jellyfish'
+class Tank
+  include Jellyfish
+  handle Jellyfish::NotFound do |e|
+    status 404
+    "You found nothing."
+  end
+end
+use Rack::ContentLength
+use Rack::ContentType, 'text/plain'
+run Tank.new
+```
+
+<!---
+GET /
+[404,
+ {'Content-Length' => '18', 'Content-Type' => 'text/plain'},
+ ["You found nothing."]]
+-->
+
 ### Access Rack::Request and params
 
 ``` ruby
@@ -352,6 +375,38 @@ GET /status
  ["30\u{2103}\n"]]
 -->
 
+### Override dispatch for processing before action
+
+We don't have before action built-in, but we could override `dispatch` in
+the controller to do the same thing. CAVEAT: Remember to call `super`.
+
+``` ruby
+require 'jellyfish'
+class Tank
+  include Jellyfish
+  controller_include Module.new{
+    def dispatch
+      @state = 'jumps'
+      super
+    end
+  }
+
+  get do
+    "Jelly #{@state}.\n"
+  end
+end
+use Rack::ContentLength
+use Rack::ContentType, 'text/plain'
+run Tank.new
+```
+
+<!---
+GET /123
+[200,
+ {'Content-Length' => '13', 'Content-Type' => 'text/plain'},
+ ["Jelly jumps.\n"]]
+-->
+
 ### Extension: MultiActions (Filters)
 
 ``` ruby
@@ -525,6 +580,9 @@ GET /123
 
 ### Jellyfish as a middleware
 
+If the Jellyfish middleware cannot find a corresponding action, it would
+then forward the request to the lower application. We call this `cascade`.
+
 ``` ruby
 require 'jellyfish'
 class Heater
@@ -556,6 +614,9 @@ GET /
 
 ### Modify response as a middleware
 
+We could also explicitly call the lower app. This would give us more
+flexibility than simply forwarding it.
+
 ``` ruby
 require 'jellyfish'
 class Heater
@@ -590,24 +651,34 @@ GET /status
  ["See header X-Temperature\n"]]
 -->
 
-### Default headers as a middleware
+### Override cascade for customized forwarding
+
+We could also override `cascade` in order to craft custom response when
+forwarding is happening. Note that whenever this forwarding is happening,
+Jellyfish won't try to merge the headers from `dispatch` method, because
+in this case Jellyfish is served as a pure proxy. As result we need to
+explicitly merge the headers if we really want.
 
 ``` ruby
 require 'jellyfish'
 class Heater
   include Jellyfish
-  get '/status' do
-    status, headers, body = jellyfish.app.call(env)
-    self.status  status
-    self.headers({'X-Temperature' => "30\u{2103}"}.merge(headers))
-    self.body    body
-  end
+  controller_include Module.new{
+    def dispatch
+      headers_merge('X-Temperature' => "35\u{2103}")
+      super
+    end
+
+    def cascade
+      status, headers, body = jellyfish.app.call(env)
+      halt [status, headers_merge(headers), body]
+    end
+  }
 end
 
 class Tank
   include Jellyfish
   get '/status' do
-    headers_merge('X-Temperature' => "35\u{2103}")
     "\n"
   end
 end
@@ -634,7 +705,7 @@ class Heater
   include Jellyfish
   get '/status' do
     env['temperature'] = 30
-    forward
+    cascade
   end
 end
 
@@ -809,6 +880,34 @@ GET /chunked
   "2\r\n3\n\r\n", "2\r\n4\n\r\n", "0\r\n\r\n"]]
 -->
 
+### Use Swagger to generate API documentation
+
+For a complete example, checkout [config.ru][].
+
+``` ruby
+require 'jellyfish'
+class Tank
+  include Jellyfish
+  get %r{^/(?<id>\d+)$}, :notes => 'This is an API note' do |match|
+    "Jelly ##{match[:id]}\n"
+  end
+end
+use Rack::ContentLength
+use Rack::ContentType, 'text/plain'
+map '/swagger' do
+  run Jellyfish::Swagger.new('', Tank)
+end
+run Tank.new
+```
+
+<!---
+GET /swagger
+[200,
+ {'Content-Type'   => 'application/json; charset=utf-8',
+  'Content-Length' => '81'},
+ ['{"swaggerVersion":"1.2","info":{},"apiVersion":"0.1.0","apis":[{"path":"/{id}"}]}']]
+-->
+
 ## CONTRIBUTORS:
 
 * Lin Jen-Shin (@godfat)
@@ -817,7 +916,7 @@ GET /chunked
 
 Apache License 2.0
 
-Copyright (c) 2012-2013, Lin Jen-Shin (godfat)
+Copyright (c) 2012-2014, Lin Jen-Shin (godfat)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/Rakefile

@@ -1,23 +1,14 @@
-# encoding: utf-8
 
 begin
   require "#{dir = File.dirname(__FILE__)}/task/gemgem"
 rescue LoadError
   sh 'git submodule update --init'
-  exec Gem.ruby, '-S', 'rake', *ARGV
+  exec Gem.ruby, '-S', $PROGRAM_NAME, *ARGV
 end
 
-Gemgem.dir = dir
-($LOAD_PATH << File.expand_path("#{Gemgem.dir}/lib")).uniq!
-
-desc 'Generate gemspec'
-task 'gem:spec' do
-  Gemgem.spec = Gemgem.create do |s|
-    require 'jellyfish/version'
-    s.name    = 'jellyfish'
-    s.version = Jellyfish::VERSION
-    %w[rack bacon muack].each{ |g| s.add_development_dependency(g) }
-  end
-
-  Gemgem.write
+Gemgem.init(dir) do |s|
+  require 'jellyfish/version'
+  s.name    = 'jellyfish'
+  s.version = Jellyfish::VERSION
+  %w[].each{ |g| s.add_runtime_dependency(g) }
 end

data/config.ru

@@ -0,0 +1,105 @@
+#!/usr/bin/env unicorn -N -Ilib
+
+require 'jellyfish'
+
+class Jelly
+  include Jellyfish
+
+  controller_include Module.new{
+    def dispatch
+      headers_merge 'Content-Type' => 'application/json; charset=utf-8',
+                    'Access-Control-Allow-Origin' => '*'
+      super
+    end
+
+    def render obj
+      ["#{Jellyfish::Json.encode(obj)}\n"]
+    end
+  }
+
+  def self.info
+    {:title       => 'Jellyfish Swagger UI',
+     :description =>
+       'This is a simple example for using Jellyfish and' \
+       ' Swagger UI altogether. You could also try the'   \
+       ' <a href="http://swagger.wordnik.com/">official Swagger UI app</a>,' \
+       ' and fill it with the swagger URL.'
+     }
+  end
+
+  def self.swagger_apiVersion
+    '1.0.0'
+  end
+
+  handle Jellyfish::NotFound do |e|
+    status 404
+    body   %Q|{"error":{"name":"NotFound"}}\n|
+  end
+
+  handle StandardError do |error|
+    jellyfish.log_error(error, env['rack.errors'])
+
+    name    = error.class.name
+    message = error.message
+
+    status 500
+    body render('error' => {'name' => name, 'message' => message})
+  end
+
+  get '/users',
+    :summary => 'List users',
+    :notes   => 'Note that we do not really have users.' do
+    render [:name => 'jellyfish']
+  end
+
+  post '/users',
+    :summary => 'Create a user',
+    :notes   => 'Here we demonstrate how to write the swagger doc.',
+    :parameters => {:name => {:type => :string, :required => true,
+                              :description => 'The name of the user'},
+                    :sane => {:type => :boolean,
+                              :description => 'If the user is sane'},
+                    :type => {:type => :string,
+                              :description => 'What kind of user',
+                              :enum => %w[good neutral evil]}},
+    :responseMessages => [{:code => 400, :message => 'Invalid name'}] do
+    render :message => "jellyfish #{request.params['name']} created."
+  end
+
+  put %r{\A/users/(?<id>\d+)},
+    :summary => 'Update a user',
+    :parameters => {:id => {:type => :integer,
+                            :description => 'The id of the user'}} do |match|
+    render :message => "jellyfish ##{match[:id]} updated."
+  end
+
+  delete %r{\A/users/(?<id>\d+)} do |match|
+    render :message => "jellyfish ##{match[:id]} deleted."
+  end
+
+  get %r{\A/posts/(?<year>\d+)-(?<month>\d+)/(?<name>\w+)},
+    :summary => 'Get a post' do |match|
+    render Hash[match.names.zip(match.captures)]
+  end
+
+  get '/posts/tags/ruby' do
+    render []
+  end
+end
+
+App = Rack::Builder.app do
+  use Rack::CommonLogger
+  use Rack::Chunked
+  use Rack::ContentLength
+  use Rack::Deflater
+
+  map '/swagger' do
+    run Jellyfish::Swagger.new('', Jelly)
+  end
+
+  run Rack::Cascade.new([Rack::File.new('public/index.html'),
+                         Rack::File.new('public'),
+                         Jelly.new])
+end
+
+run App