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.
  #
  # ```
  # 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 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