lib/tynn/session.rb in tynn-0.0.4 vs lib/tynn/session.rb in tynn-1.0.0.rc1

@@ -1,14 +1,85 @@
+# 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:
-    options = options.dup
-    options[:http_only] ||= true
-
     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