tynn 1.4.0 → 2.0.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4814f92f9f4fc3914fd79a2b2756caae11b6dcf3
-  data.tar.gz: 24e79b0a795e4abc44ffe65d43ee49cb6e3af3a8
+  metadata.gz: 3428a8bf437b03bf9e9dc2d2568143010f5a8be7
+  data.tar.gz: 9a36c6091a73ced16b4b5a5e9f8cec60fa6fd39e
 SHA512:
-  metadata.gz: 69fa5b9b8a69a5709b58435287e90c8a547e2dc98c80ded0b1dc7c46ac306e4f02b77819ee52619ff6c8cfae27ef4bbaa57a36b18ad2e815928cb49bbb9d4f9c
-  data.tar.gz: 4e6b16cd569034ecbaf6f9b671b5327264035988480659d21154e7694b64ccebfcabc05deee3acf80dc25c16b3232feadaa4e256701b72e8576e8672fedd2e12
+  metadata.gz: 25196be28e4b69d4d0ea609bcdfa7fa08276716c6e94753347ac17c8dfad6d6c9f9b390559b79ca9c9f67fbec78dec2379a481c21497460768502649bc95c63e
+  data.tar.gz: a5bdf9e80a0d95d9d172264a00612dc0c86666a1c25c761598363e100279f6c32d09d20235d3d1a0216a0ed29f2890a80da263e431c9e30f125aaa3081a418fc

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Francesco Rodríguez and contributors
+Copyright (c) 2015-2016 Francesco Rodríguez and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,50 +1,565 @@
-Tynn [![Build Status](https://travis-ci.org/frodsan/tynn.svg)](https://travis-ci.org/frodsan/tynn)
-====
+# Tynn
 
-A thin library for web development.
+[![Build Status](https://travis-ci.org/frodsan/tynn.svg?branch=master)](https://travis-ci.org/frodsan/tynn)
+[![Dependency Status](https://gemnasium.com/badges/github.com/frodsan/tynn.svg)](https://gemnasium.com/github.com/frodsan/tynn)
+[![Code Climate](https://codeclimate.com/github/frodsan/tynn/badges/gpa.svg)](https://codeclimate.com/github/frodsan/tynn)
+[![Join the chat at https://gitter.im/frodsan/tynn](https://badges.gitter.im/frodsan/tynn.svg)](https://gitter.im/frodsan/tynn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Description
------------
+A thin library for web development in Ruby.
 
-Tynn is a thin abstraction on top of [Syro][syro], a very simple and fast
-router for web applications.
+* [Getting Started](#getting-started)
+  * [Assumptions](#assumptions)
+  * [Installation](#installation)
+  * [Hello World!](#hello-world)
+  * [Under the Hood](#under-the-hood)
+  * [Tynn on Rack](#tynn-on-rack)
+* [Routing Basics](#routing-basics)
+* [Managing Request and Response](#managing-request-and-response)
+  * [Redirecting a Request](#redirecting-a-request)
+  * [Halting a Request](#halting-a-request)
+* [Extending Tynn](#extending-tynn)
+  * [Middleware](#middleware)
+  * [Plugins](#plugins)
+  * [Settings](#settings)
+* [Default Plugins](#default-plugins)
+  * [Environments](#environments)
+  * [Method Override](#method-override)
+  * [Static Files](#static-files)
+* [Security](#security)
+* [Testing](#testing)
+* [API Reference](http://api.tynn.xyz/2.0.0)
+* [Changelog](#changelog)
+* [Development](#development)
+* [Contributing](#contributing)
+* [Build History](#build-history)
+* [License](#license)
 
-Usage
------
+**NOTE. There is an online version of this README at http://tynn.xyz/.**
 
-Here's a minimal application:
+## Getting Started
+
+Tynn is a minimal and flexible library for building JSON web services and web applications in Ruby. It's designed with two main goals: simplicity and extensibility.
+
+Tynn offers the essentials to handle HTTP requests and also includes mechanisms to easily extend its functionality through [plugins](#plugins) and [middleware][middleware]. Tynn ships with a set of [default plugins](#default-plugins) that you can combine to meet your needs.
+
+Tynn is not a framework. There is no built-in support for connecting to databases or a common application architecture. This gives you the freedom to choose the appropiate tools for the job at hand.
+
+Like most web libraries in Ruby, Tynn is built on top of [Rack], a Ruby webserver interface. Because of this, it has the benefits of using existing libraries and a variety of web servers for free.
+
+Tynn takes design cues from other web libraries like [Rails], [Sinatra], and [Cuba]. Under the hood, it uses [Syro], a fast router for web applications.
+
+### Assumptions
+
+This section serves as a high-level introduction to the core features of Tynn. It also covers installation and walks through the creation of a simple application. To get the most out of it, it's recommended to have a basic knowledge about Ruby and HTTP.
+
+### Installation
+
+Installing Tynn is pretty straightforward. From the command line, use the `gem` command:
+
+```
+$ gem install tynn
+```
+
+If you prefer to use [Bundler] instead, set up the environment with:
+
+```
+$ bundle init
+```
+
+Then, update the contents of the generated Gemfile to:
+
+```ruby
+source "https://rubygems.org"
+
+gem "tynn", "~> 2.0"
+```
+
+Finally, install the dependencies with:
+
+```
+$ bundle install
+```
+
+Now you can create your first Tynn app!
+
+### Hello World!
+
+Let's start with a minimal application. Open your preferred text editor and enter the following code:
 
 ```ruby
-# config.ru
 require "tynn"
 
 Tynn.define do
-  root do
+  on root? do
+    get do
+      res.write("Hello World!")
+    end
+  end
+end
+```
+
+Save this file as `app.rb`. Once you've done so, create another file called `config.ru` with the contents shown below:
+
+```ruby
+require File.expand_path("app", __dir__)
+
+run(Tynn)
+```
+
+You already have a functional application! The syntax is very readable, but we'll discuss the details in a moment. To see it in action, you need to start a web server. You can do this by typing `rackup` in the command line.
+
+![Starting a Web Server](https://raw.githubusercontent.com/frodsan/tynn/master/docs/images/rackup.png)
+
+> **NOTE:** To stop the web server, hit `Ctrl+C` in the terminal window where it's running. To verify that the server has stopped you should see your command prompt cursor again.
+
+Now open a browser window and navigate to http://localhost:9292 to see the greeting message.
+
+![Hello World!](https://raw.githubusercontent.com/frodsan/tynn/master/docs/images/hello-world.png)
+
+### Under the hood
+
+Tynn is all about routing. Routing determines how an application should respond to a client request to a URI (or path) and a specific HTTP request method. In our previous example, that would be the root path (`/`) and the HTTP GET method.
+
+To get a look on what's happening under the hood, let's see line 4:
+
+```ruby
+on root? do
+  # ...
+end
+```
+
+That's a little taste of what we call routing matchers in Tynn. The purpose of the `on` matcher is to execute the given block only if the given argument returns `true`. In our case, `root?` returns `true` because we are accessing the root path (`/`) from our browser.
+
+One line below there is another type of matcher:
+
+```ruby
+get do
+  res.write("Hello World!")
+end
+```
+
+Tynn also includes methods for matching all the HTTP verbs (GET, POST, etc.). By default, if there are no other matchers before a verb matcher, it automatically checks that the current request is for the root path. The above example can be written as:
+
+```ruby
+Tynn.define do
+  get do
     res.write("Hello World!")
   end
 end
+```
+
+> **Note.** If you're not familiar with the HTTP methods, check out this [Wikipedia page](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods).
+
+### Tynn on Rack
+
+The last part of the puzzle is the `config.ru` file. As we mentioned earlier, Tynn is built on top of Rack ... but what is Rack?
+
+Rack deals with HTTP requests. It provides a minimal interface between web servers supporting Ruby and Ruby web frameworks. Without Rack, Tynn would have to implement its own handler for each Ruby web server.
 
+To run the hello world application you used `rackup`, one of the tools that comes with Rack. To use `rackup`, you need to supply a `config.ru` file. This file connects the Rack interface with our Tynn application through the `run` method.
+
+```ruby
 run(Tynn)
 ```
 
-Check [Getting Started][start] for more information.
+Rack also figures out which server you have available in your system. When we used `rackup`, it fired up WEBrick, a web server built into Ruby by default.
+
+```
+$ rackup
+[2016-05-14 00:25:11] INFO WEBrick 1.3.1
+```
+
+Most popular web servers, like [Puma], [Unicorn] or [Thin], have built-in support for Rack, and thus support Tynn too. You can read more about Rack visiting their home page: http://rack.github.io/.
+
+## Routing basics
+
+This section covers the routing features of Tynn, such as route definitions, composing applications, and so on.
+
+## Managing Request and Response
+
+This section covers the many features Tynn provides to handle requests and responses.
+
+### Redirecting a Request
+
+To redirect a request to a different location, use `res.redirect`.
+
+```ruby
+res.redirect("/pricing")
+```
+
+To redirect to a different site, use a fully-qualified URL.
+
+```ruby
+res.redirect("https://google.com")
+```
+
+By default, the status code is set to `302` (Found). To set a different status code, pass an integer as a second parameter.
+
+```ruby
+res.redirect("/projects/1", 301)
+```
+
+### Halting a Request
+
+To immediately stop a request within a route, you can use the `halt` method.
+
+```ruby
+halt([status, headers, body])
+```
+
+Use `res.finish` to return a response as per Rack's specification.
+
+```ruby
+if current_user.nil?
+  res.redirect("/login")
+
+  halt(res.finish)
+end
+
+# This won't be reached if current_user is nil
+```
+
+## Extending Tynn
+
+### Middleware
+
+Tynn runs on [Rack](https://github.com/rack/rack). Therefore it is possible
+to use Rack middleware in Tynn. This is how you add a middleware (for example
+`YourMiddleware`) to your app:
+
+```ruby
+Tynn.use(YourMiddleware)
+```
+
+You can use any Rack middleware to your app, it is not specific to Tynn. You
+can find a list of Rack middleware [here][middleware].
+
+[middleware]: https://github.com/rack/rack/wiki/list-of-middleware
+
+### Plugins
+
+A way to extend Tynn is to use the plugin API. A plugin is just a module which can contain any of the following rules:
+
+- If a `ClassMethods` module is defined, it extends the application class.
+
+- If a `InstanceMethods` module is defined, it's included in the application.
+
+- If a `setup` method is defined, it will be called last. This method can be used to configure the plugin.
+
+The following is a complete example of the plugin API.
+
+```ruby
+require "valuta"
+
+module CurrencyHelper
+  def self.setup(app, currency: "$")
+    self.currency = currency
+  end
+
+  module ClassMethods
+    def currency
+      @currency
+    end
+
+    def currency=(currency)
+      @currency = currency
+    end
+  end
+
+  module InstanceMethods
+    def to_currency(value)
+      Valuta.convert(value, prefix: self.class.currency)
+    end
+  end
+end
+```
+
+To load the plugin into the application, use the `plugin` method.
+
+```ruby
+App.plugin(CurrencyHelper, currency: "$")
+```
+
+Here is the plugin in action:
+
+```ruby
+App.currency # => "$"
+
+App.define do
+  get do
+    res.write(to_currency(4567))
+  end
+end
+# GET / => 200 $4,567
+```
+
+### Settings
+
+Each application has a `settings` hash where configuration can be stored. By default, settings are inherited.
+
+```ruby
+Tynn.set(:layout, "layout")
+
+class Guests < Tynn; end
+class Users < Tynn; end
+class Adminds < Tynn; end
+
+Users.set(:layout, "users/layout")
+Admins.set(:layout, "admins/layout")
+
+Guests.settings[:layout] # => "layout"
+Users.settings[:layout]  # => "users/layout"
+Admins.settings[:layout] # => "admins/layout"
+```
+
+This features comes in handy when authoring plugins.
+
+```ruby
+module CurrencyHelper
+  module ClassMethods
+    def currency=(currency)
+      set(:currency, currency)
+    end
+
+    def currency
+      settings.fetch(:currency, "$")
+    end
+  end
+end
+```
+
+## Default Plugins
+
+Tynn ships with a set of default plugins:
+
+| Name                  | Description
+| --------------------- | -----------------------------------------------------------------
+| [Tynn::Environment]   | Adds helper methods to get and check the current environment.
+| [Tynn::JSON]          | Adds helper methods for json generation.
+| [Tynn::Render]        | Adds support for rendering templates through different engines.
+| [Tynn::Session]       | Adds simple cookie based session management.
+| [Tynn::Static]        | Adds support for static files (javascript files, images, etc.).
+
+The following sections cover the default plugins and extensions shipped with Tynn.
+
+### Environments
+
+Tynn ships with [Tynn::Environment] to set and check the current environment for the application.
+
+```ruby
+require "tynn"
+require "tynn/environment"
+
+Tynn.plugin(Tynn::Environment)
+```
+
+The default environment is based on the `RACK_ENV` environment variable.
+
+```ruby
+ENV["RACK_ENV"]
+# => "test"
+
+Tynn.environment
+# => :test
+```
+
+If `ENV["RACK_ENV"]` is `nil`, the default value is `:development`.
+
+```ruby
+Tynn.environment
+# => :development
+```
+
+To change the current environment, use the `environment=` method.
+
+```ruby
+Tynn.environment = :development
+
+Tynn.environment
+# => :development
+```
+
+To check the current environment, use: `development?`, `test?`,
+`production?` or `staging?`.
+
+```ruby
+Tynn.plugin(Tynn::SSL) if Tynn.production?
+```
+
+Perform operations on specific environments with the `configure` method.
+
+```ruby
+Tynn.configure(:development) do |app|
+  app.use(Tynn::Static, %w(/js /css /images))
+end
+
+Tynn.configure(:production) do |app|
+  app.use(Tynn::SSL)
+end
+```
+
+### Method Override
+
+HTML Forms only support GET and POST requests. To perform other actions such as PUT, PATCH or DELETE, use the [Rack::MethodOverride] middleware. Note that there is no need to add any new dependencies to the application as it's included in Rack already.
+
+```ruby
+Tynn.use(Rack::MethodOverride)
+```
+
+This uses a POST form to simulate a request with a non-supported method. In order to succeed, a hidden input field, with the name `_method` and the method name as the value, needs to be included. The following example simulates a PUT
+request.
+
+```html
+<form method="POST" action="/posts/1">
+  <input type="hidden" name="_method" value="PUT">
+  <!-- ... -->
+</form>
+```
+
+Now, this will trigger the `put` matcher in the application.
+
+```ruby
+Posts.define do
+  put do
+    post.update(req.params["post"])
+  end
+end
+```
+
+### Static Files
+
+Tynn ships with [Tynn::Static] to serve static files such as images, CSS, JavaScript and others.
+
+```ruby
+require "tynn"
+require "tynn/static"
+
+Tynn.plugin(Tynn::Static, %w(/js /css /images))
+```
+
+By default, static files are served from the folder `public` in the current directory. You can specify a different location by passing the `:root` option:
+
+```ruby
+Tynn.plugin(Tynn::Static, %w(/js /css /images), root: "assets")
+```
+
+As you can see in the table below, the name of static directory is not included in the URL because the files are looked up relative to that directory.
+
+
+| File                         | URL                                    |
+| ---------------------------- | -------------------------------------- |
+| ./public/js/application.js   | http://example.org/js/application.js   |
+| ./public/css/application.css | http://example.org/css/application.css |
+| ./public/images/logo.png     | http://example.org/images/logo.png     |
+
+It's important to mention that the path of the static directory path is relative to the directory where you run the application. If you run the application from another directory, it's safer to use an absolute path:
+
+```ruby
+Tynn.plugin(
+  Tynn::Static,
+  %w(/js /css /images),
+  root: File.expand_path("public", __dir__)
+)
+```
+
+## Security
+
+## Testing
+
+Tynn ships with [Tynn::Test], a simple helper class to simulate requests to your application.
+
+```ruby
+require "tynn"
+require "tynn/test"
+
+Tynn.define do
+  root do
+    res.write("hei")
+  end
+end
+
+app = Tynn::Test.new
+app.get("/")
+
+200   == app.res.status # => true
+"hei" == app.res.body   # => true
+```
+
+[Tynn::Test] is test-framework agnostic. The following example uses [Minitest]:
+
+```ruby
+require "minitest/autorun"
+require "tynn/test"
+
+class GuestsRouteTest < Minitest::Test
+  def setup
+    @app = Tynn::Test.new
+  end
+
+  def test_home
+    @app.get("/")
+
+    assert_equal 200, @app.res.status
+    assert_equal "Hello World!", @app.res.body
+    assert_equal "text/html", @app.res["Content-Type"]
+  end
+end
+```
+
+If this is not of your flavor, you can use any Rack-based testing library or framework, like: [Rack::Test] or [Capybara].
+
+## Changelog
+
+To learn about new features, bug fixes, and changes, please refer to the [CHANGELOG](https://github.com/frodsan/tynn/blob/master/CHANGELOG.md).
+
+## Development
+
+Fork the project with:
+
+```
+$ git clone git@github.com:frodsan/tynn.git
+```
+
+To install dependencies, use:
+
+```
+$ bundle install
+```
+
+To run the test suite, do:
+
+```
+$ rake test
+```
 
-Documentation
--------------
+## Contributing
 
-See our website: <http://tynn.xyz/>.
+Use [GitHub Issues](https://github.com/frodsan/tynn/issues) for reporting bugs, discussing features and general feedback. If you've found a problem in Tynn, be sure to check the [past issues](https://github.com/frodsan/tynn/issues?state=closed) before open a new one.
 
-Contributing
-------------
+## Build History
 
-Please see the [CONTRIBUTING][contributing] file for more information.
+[![Build History](https://buildstats.info/travisci/chart/frodsan/tynn?branch=master)](https://travis-ci.org/frodsan/tynn/builds)
 
-License
--------
+## License
 
-Tynn is released under the [MIT License][mit].
+Tynn is released under the [MIT License](http://www.opensource.org/licenses/MIT).
 
-[contributing]: https://github.com/frodsan/tynn/blob/master/CONTRIBUTING.md
-[mit]: http://www.opensource.org/licenses/MIT
-[start]: http://tynn.xyz/getting-started.html
+[bundler]: http://bundler.io/
+[capybara]: https://github.com/jnicklas/capybara
+[cuba]: http://cuba.is/
+[minitest]: https://github.com/seattlerb/minitest
+[puma]: http://puma.io/
+[rack]: http://rack.github.io/
+[rack::test]: https://github.com/brynary/rack-test
+[rack::methodoverride]: http://www.rubydoc.info/github/rack/rack/Rack/MethodOverride
+[rails]: http://rubyonrails.org/
+[sinatra]: http://www.sinatrarb.com/
 [syro]: http://soveran.github.io/syro/
+[thin]: http://code.macournoyer.com/thin/
+[tynn::environment]: http://api.tynn.xyz/2.0.0/Tynn/Environment.html
+[tynn::json]: http://api.tynn.xyz/2.0.0/Tynn/JSON.html
+[tynn::render]: http://api.tynn.xyz/2.0.0/Tynn/Render.html
+[tynn::session]: http://api.tynn.xyz/2.0.0/Tynn/Session.html
+[tynn::static]: http://api.tynn.xyz/2.0.0/Tynn/Static.html
+[tynn::test]: http://api.tynn.xyz/2.0.0/Tynn/Test.html
+[unicorn]: https://unicorn.bogomips.org/