tynn 1.0.0.rc1 → 1.0.0.rc2

data/lib/tynn/protection.rb

@@ -1,13 +1,42 @@
 require_relative "secure_headers"
 
-module Tynn::Protection
-  def self.setup(app, ssl: false, hsts: {}) # :nodoc:
-    app.helpers(Tynn::SecureHeaders)
+class Tynn
+  # Adds security measures against common attacks.
+  #
+  # ```
+  # require "tynn"
+  # require "tynn/protection"
+  #
+  # Tynn.helpers(Tynn::Protection)
+  # ```
+  #
+  # If you are using SSL/TLS (HTTPS), it's recommended to set
+  # the `:ssl` option:
+  #
+  # ```
+  # require "tynn"
+  # require "tynn/protection"
+  #
+  # Tynn.helpers(Tynn::Protection, ssl: true)
+  # ```
+  #
+  # By default, it includes the following security helpers:
+  #
+  # * Tynn::SecureHeaders
+  #
+  # If the `:ssl` option is `true`, includes:
+  #
+  # * Tynn::SSL
+  #
+  module Protection
+    def self.setup(app, ssl: false, hsts: {}) # :nodoc:
+      app.helpers(Tynn::SecureHeaders)
 
-    if ssl
-      require_relative "ssl"
+      if ssl
+        require_relative "ssl"
 
-      app.helpers(Tynn::SSL, hsts: hsts)
+        app.helpers(Tynn::SSL, hsts: hsts)
+      end
     end
   end
 end

data/lib/tynn/render.rb

@@ -1,56 +1,48 @@
 require "tilt"
 
-module Tynn::Render
-  def self.setup(app, options = {}) # :nodoc:
-    options = options.dup
-
-    options[:engine]  ||= "erb"
-    options[:layout]  ||= "layout"
-    options[:views]   ||= File.expand_path("views", Dir.pwd)
-
-    options[:options] ||= {}
-    options[:options] = {
-      default_encoding: Encoding.default_external,
-      outvar: "@_output"
-    }.merge!(options[:options])
-
-    app.settings[:render] ||= options
-  end
-
-  module ClassMethods
-    def layout(layout)
-      settings[:render][:layout] = layout
+class Tynn
+  module Render
+    def self.setup(app, options = {}) # :nodoc:
+      app.settings.update(
+        layout: options.fetch(:layout, "layout"),
+        views: options.fetch(:views, File.expand_path("views", Dir.pwd)),
+        engine: options.fetch(:engine, "erb"),
+        engine_opts: {
+          default_encoding: Encoding.default_external,
+          outvar: "@_output"
+        }.merge!(options.fetch(:options, {}))
+      )
     end
-  end
 
-  def render(template, locals = {}, layout = settings[:render][:layout])
-    res.headers[Rack::CONTENT_TYPE] ||= Syro::Response::DEFAULT
+    def render(template, locals = {}, layout = settings[:layout])
+      res.headers[Rack::CONTENT_TYPE] ||= Syro::Response::DEFAULT
 
-    res.write(view(template, locals, layout))
-  end
+      res.write(view(template, locals, layout))
+    end
 
-  def view(template, locals = {}, layout = settings[:render][:layout])
-    return partial(layout, locals.merge(content: partial(template, locals)))
-  end
+    def view(template, locals = {}, layout = settings[:layout])
+      return partial(layout, locals.merge(content: partial(template, locals)))
+    end
 
-  def partial(template, locals = {})
-    return tilt(template_path(template), locals, settings[:render][:options])
-  end
+    def partial(template, locals = {})
+      return tilt(template_path(template), locals, settings[:engine_opts])
+    end
 
-  private
+    private
 
-  def tilt(file, locals = {}, opts = {})
-    return tilt_cache.fetch(file) { Tilt.new(file, 1, opts) }.render(self, locals)
-  end
+    def tilt(file, locals = {}, opts = {})
+      return tilt_cache.fetch(file) { Tilt.new(file, 1, opts) }.render(self, locals)
+    end
 
-  def tilt_cache
-    return Thread.current[:tilt_cache] ||= Tilt::Cache.new
-  end
+    def tilt_cache
+      return Thread.current[:tilt_cache] ||= Tilt::Cache.new
+    end
 
-  def template_path(template)
-    dir = settings[:render][:views]
-    ext = settings[:render][:engine]
+    def template_path(template)
+      dir = settings[:views]
+      ext = settings[:engine]
 
-    return File.join(dir, "#{ template }.#{ ext }")
+      return File.join(dir, "#{ template }.#{ ext }")
+    end
   end
 end

data/lib/tynn/request.rb

@@ -1,4 +1,6 @@
 class Tynn
+  # It provides convenience methods for pulling out information
+  # from a request.
   class Request < Rack::Request
   end
 end

data/lib/tynn/response.rb

@@ -1,5 +1,39 @@
 class Tynn
+  # It provides convenience methods to construct a Rack response.
+  #
+  # ```
+  # res = Tynn::Response.new
+  # res.status = 200
+  # res["Content-Type"] = "text/html"
+  # res.write("foo")
+  # ```
+  #
+  # [Tynn::Response#finish][finish] returns a response as per
+  # [Rack's specification][rack-spec].
+  #
+  # ```
+  # res.finish
+  # # => [200, { "Content-Type" => "text/html", "Content-Length" => 3 }, ["foo"]]
+  # ```
+  #
+  # [finish]: #method-i-finish
+  # [rack-spec]: http://www.rubydoc.info/github/rack/rack/master/file/SPEC
+  #
   class Response < Syro::Response
+    ##
+    # :method: new
+    # :call-seq: new(headers = {})
+    #
+    # Initializes a new response object with the given `headers`.
+    #
+    # ```
+    # Tynn::Response.new.headers
+    # # => {}
+    #
+    # Tynn::Response.new("Content-Type" => "text/plain").headers
+    # # => { "Content-Type" => "text/plain" }
+    # ```
+
     ##
     # :method: []
     #
@@ -48,9 +82,9 @@ class Tynn
     #     # => [404, {}, []]
     #
     #     res.status = nil
-    #     res.write("yo!")
+    #     res.write("yo")
     #     res.finish
-    #     # => [200, { "Content-Type" => "text/html" }, ["yo!"]]
+    #     # => [200, { "Content-Type" => "text/html", "Content-Length" => 2 }, ["yo"]]
 
     ##
     # :method: headers

data/lib/tynn/secure_headers.rb

@@ -1,43 +1,45 @@
-# Adds security related HTTP headers.
-#
-# ```
-# require "tynn"
-# require "tynn/secure_headers"
-#
-# Tynn.helpers(Tynn::SecureHeaders)
-# ```
-#
-# This helper applies the following headers:
-#
-# * **X-Content-Type-Options:** Prevents IE and Chrome from
-#   [content type sniffing][mime-sniffing].
-#
-# * **X-Frame-Options (XFO):** Provides [Clickjacking][clickjacking]
-#   protection. Check the [X-Frame-Options draft][x-frame-options] for
-#   more information.
-#
-# * **X-Permitted-Cross-Domain-Policies:** Restricts Adobe Flash Player's
-#   access to data. Check this [article][pcdp] for more information.
-#
-# * **X-XSS-Protection:** Enables the [XSS][xss] protection filter built
-#   into IE, Chrome and Safari. This filter is usually enabled by default,
-#   the use of this header is to re-enable it if it was disabled by the user.
-#
-# [clickjacking]: https://www.owasp.org/index.php/Clickjacking
-# [mime-sniffing]: https://msdn.microsoft.com/library/gg622941(v=vs.85).aspx
-# [pcdp]: https://www.adobe.com/devnet/adobe-media-server/articles/cross-domain-xml-for-streaming.html
-# [x-frame-options]: https://tools.ietf.org/html/draft-ietf-websec-x-frame-options-02
-# [xss]: https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)
-#
-module Tynn::SecureHeaders
-  HEADERS = {
-    "X-Content-Type-Options" => "nosniff",
-    "X-Frame-Options" => "SAMEORIGIN",
-    "X-Permitted-Cross-Domain-Policies" => "none",
-    "X-XSS-Protection" => "1; mode=block"
-  } # :nodoc:
+class Tynn
+  # Adds security related HTTP headers.
+  #
+  # ```
+  # require "tynn"
+  # require "tynn/secure_headers"
+  #
+  # Tynn.helpers(Tynn::SecureHeaders)
+  # ```
+  #
+  # This helper applies the following headers:
+  #
+  # * **X-Content-Type-Options:** Prevents IE and Chrome from
+  #   [content type sniffing][mime-sniffing].
+  #
+  # * **X-Frame-Options (XFO):** Provides [Clickjacking][clickjacking]
+  #   protection. Check the [X-Frame-Options draft][x-frame-options] for
+  #   more information.
+  #
+  # * **X-Permitted-Cross-Domain-Policies:** Restricts Adobe Flash Player's
+  #   access to data. Check this [article][pcdp] for more information.
+  #
+  # * **X-XSS-Protection:** Enables the [XSS][xss] protection filter built
+  #   into IE, Chrome and Safari. This filter is usually enabled by default,
+  #   the use of this header is to re-enable it if it was disabled by the user.
+  #
+  # [clickjacking]: https://www.owasp.org/index.php/Clickjacking
+  # [mime-sniffing]: https://msdn.microsoft.com/library/gg622941(v=vs.85).aspx
+  # [pcdp]: https://www.adobe.com/devnet/adobe-media-server/articles/cross-domain-xml-for-streaming.html
+  # [x-frame-options]: https://tools.ietf.org/html/draft-ietf-websec-x-frame-options-02
+  # [xss]: https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)
+  #
+  module SecureHeaders
+    HEADERS = {
+      "X-Content-Type-Options" => "nosniff",
+      "X-Frame-Options" => "SAMEORIGIN",
+      "X-Permitted-Cross-Domain-Policies" => "none",
+      "X-XSS-Protection" => "1; mode=block"
+    } # :nodoc:
 
-  def default_headers # :nodoc:
-    return super.merge(HEADERS)
+    def default_headers # :nodoc:
+      return super.merge(HEADERS)
+    end
   end
 end

data/lib/tynn/session.rb

@@ -1,85 +1,87 @@
-# Adds simple cookie based session management. If a secret token is
-# given, it signs the cookie data to ensure that it cannot be altered
-# by unauthorized means.
-#
-# ```
-# require "tynn"
-# require "tynn/session"
-#
-# Tynn.helpers(Tynn::Session, secret: "__change_me__")
-#
-# Tynn.define do
-#   root do
-#     res.write(sprintf("hei %s", session[:username]))
-#   end
-#
-#   on(:username) do |username|
-#     session[:username] = username
-#   end
-# end
-# ```
-#
-# The following command generates a cryptographically secure secret ready
-# to use:
-#
-# ```
-# $ ruby -r securerandom -e "puts SecureRandom.hex(64)"
-# ```
-#
-# It's important to keep the token secret. Knowing the token allows an
-# attacker to tamper the data. So, it's recommended to load the token
-# from the environment.
-#
-# ```
-# Tynn.helpers(Tynn::Session, secret: ENV["SESSION_SECRET"])
-# ```
-#
-# Under the hood, Tynn::Session uses the [Rack::Session::Cookie][rack-session]
-# middleware. Thus, supports all the options available for this middleware.
-#
-# * `:key` - the name of the cookie. Defaults to `"rack.session"`.
-# * `:expire_after` - sets the lifespan of the cookie. If `nil`,
-#     the cookie will be deleted after the user close the browser.
-#     Defaults to `nil`.
-# * `:httponly` - if `true`, sets the [HttpOnly][cookie-httponly] attribute.
-#   This mitigates the risk of client side scripting accessing the cookie.
-#   Defaults to `true`.
-# * `:secure` - if `true`, sets the [Secure][cookie-secure] attribute.
-#   This tells the browser to only transmit the cookie over HTTPS. Defaults
-#   to `false`.
-#
-# ```
-# Tynn.helpers(
-#   Tynn::Session,
-#   key: "app",
-#   secret: ENV["SESSION_SECRET"],
-#   expire_after: 36_000, # seconds
-#   httponly: true,
-#   secure: true
-# )
-# ```
-#
-# [cookie-httponly]: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet#HttpOnly_Attribute
-# [cookie-secure]: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet#Secure_Attribute
-# [rack-session]: http://www.rubydoc.info/gems/rack/Rack/Session/Cookie
-#
-module Tynn::Session
-  RACK_SESSION = "rack.session".freeze # :nodoc:
-
-  def self.setup(app, options = {}) # :nodoc:
-    app.use(Rack::Session::Cookie, options)
-  end
-
-  # Returns the session hash.
+class Tynn
+  # Adds simple cookie based session management. If a secret token is
+  # given, it signs the cookie data to ensure that it cannot be altered
+  # by unauthorized means.
   #
   # ```
-  # session # => {}
+  # require "tynn"
+  # require "tynn/session"
   #
-  # session[:foo] = "foo"
-  # session[:foo] # => "foo"
+  # Tynn.helpers(Tynn::Session, secret: "__change_me__")
+  #
+  # Tynn.define do
+  #   root do
+  #     res.write(sprintf("hei %s", session[:username]))
+  #   end
+  #
+  #   on(:username) do |username|
+  #     session[:username] = username
+  #   end
+  # end
   # ```
   #
-  def session
-    return env[RACK_SESSION]
+  # The following command generates a cryptographically secure secret ready
+  # to use:
+  #
+  # ```
+  # $ ruby -r securerandom -e "puts SecureRandom.hex(64)"
+  # ```
+  #
+  # It's important to keep the token secret. Knowing the token allows an
+  # attacker to tamper the data. So, it's recommended to load the token
+  # from the environment.
+  #
+  # ```
+  # Tynn.helpers(Tynn::Session, secret: ENV["SESSION_SECRET"])
+  # ```
+  #
+  # Under the hood, Tynn::Session uses the [Rack::Session::Cookie][rack-session]
+  # middleware. Thus, supports all the options available for this middleware.
+  #
+  # * `:key` - the name of the cookie. Defaults to `"rack.session"`.
+  # * `:expire_after` - sets the lifespan of the cookie. If `nil`,
+  #     the cookie will be deleted after the user close the browser.
+  #     Defaults to `nil`.
+  # * `:httponly` - if `true`, sets the [HttpOnly][cookie-httponly] attribute.
+  #   This mitigates the risk of client side scripting accessing the cookie.
+  #   Defaults to `true`.
+  # * `:secure` - if `true`, sets the [Secure][cookie-secure] attribute.
+  #   This tells the browser to only transmit the cookie over HTTPS. Defaults
+  #   to `false`.
+  #
+  # ```
+  # Tynn.helpers(
+  #   Tynn::Session,
+  #   key: "app",
+  #   secret: ENV["SESSION_SECRET"],
+  #   expire_after: 36_000, # seconds
+  #   httponly: true,
+  #   secure: true
+  # )
+  # ```
+  #
+  # [cookie-httponly]: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet#HttpOnly_Attribute
+  # [cookie-secure]: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet#Secure_Attribute
+  # [rack-session]: http://www.rubydoc.info/gems/rack/Rack/Session/Cookie
+  #
+  module Session
+    RACK_SESSION = "rack.session".freeze # :nodoc:
+
+    def self.setup(app, options = {}) # :nodoc:
+      app.use(Rack::Session::Cookie, options)
+    end
+
+    # Returns the session hash.
+    #
+    # ```
+    # session # => {}
+    #
+    # session[:foo] = "foo"
+    # session[:foo] # => "foo"
+    # ```
+    #
+    def session
+      return env[RACK_SESSION]
+    end
   end
 end