Rodauth Internals¶ ↑

Rodauth’s implementation heavily uses metaprogramming in order to DRY up the codebase, which can be a little intimidating to developers who are not familiar with the codebase. This guide explains how Rodauth is built, which should make the internals easier to understand.

Object Model¶ ↑

First, let’s talk about the basic parts of Rodauth.

Rodauth::Auth¶ ↑

Rodauth::Auth is the core of rodauth. If a user calls rodauth inside their Roda application, they get a Rodauth::Auth subclass instance. Rodauth’s configuration DSL is designed to build a Rodauth::Auth subclass appropriate to the application, by loading only the features that are needed, and overriding defaults as appropriate.

Rodauth::Configuration¶ ↑

Inside the block you pass to plugin :rodauth, self is an instance of this class. This class is mostly empty, as most of Rodauth is implemented as separate features, and the configuration for each feature is loaded as a separate module into this instance.

Rodauth::Feature¶ ↑

Each of the parts of rodauth that you can use is going to be a separate feature. Rodauth::Feature is a Module subclass, and every rodauth feature you load is an instance of this class, which is included in the Rodauth::Auth subclass used by the Roda application. Rodauth::Feature has many methods designed to make building Rodauth features easier by defining methods in the Rodauth::Feature instance.

Rodauth::FeatureConfiguration¶ ↑

Just as each feature is a module included in the Rodauth::Auth subclass for the application, each feature also contains a configuration module that is an instance of Rodauth::FeatureConfiguration (also a module subclass). For each feature you load into the Rodauth configuration, the Rodauth::Configuration instance is extended with the feature’s Rodauth::FeatureConfiguration instance, which is what makes the feature’s configuration methods available inside the plugin :rodauth block. This is why you need to enable the features in Rodauth before configuring them.

Object Model Example¶ ↑

Here’s some commented output hopefully showing the relation between the different parts

Roda.plugin :rodauth do
  self                       # => #<Rodauth::Configuration> (instance)
  auth                       # => Rodauth::Auth subclass

  singleton_class.ancestors  # => [#<Class:#<Rodauth::Configuration>> (singleton class of self),
                             #     Rodauth::FeatureConfiguration::Base (instance of Rodauth::FeatureConfiguration),
                             #     Rodauth::Configuration,
                             #     ...]
  auth.ancestors             # => [Rodauth::Auth subclass,
                             #     Rodauth::Base (instance of Rodauth::Feature),
                             #     Rodauth::Auth,
                             #     ...]

  enable :login

  singleton_class.ancestors  # => [#<Class:#<Rodauth::Configuration>> (singleton class of self),
                             #     Rodauth::FeatureConfiguration::Login (instance of Rodauth::FeatureConfiguration),
                             #     Rodauth::FeatureConfiguration::Base (instance of Rodauth::FeatureConfiguration),
                             #     Rodauth::Configuration,
                             #     ...]
  auth.ancestors             # => [Rodauth::Auth subclass,
                             #     Rodauth::Login (instance of Rodauth::Feature),
                             #     Rodauth::Base (instance of Rodauth::Feature),
                             #     Rodauth::Auth,
                             #     ...]
end

Roda.rodauth                 # => Rodauth::Auth subclass
Roda.rodauth.ancestors       # => [Rodauth::Auth subclass,
                             #     Rodauth::Login (instance of Rodauth::Feature),
                             #     Rodauth::Base (instance of Rodauth::Feature),
                             #     Rodauth::Auth,
                             #     ...]

Roda.route do |r|
  rodauth                    # => Rodauth::Auth subclass instance
end

Feature Creation Example¶ ↑

Here’s a heavily commented example showing what is going on inside a Rodauth feature.

module Rodauth
  # Feature.define takes a symbol, specifying the name of the feature. This
  # is the same symbol you would pass to enable when loading the feature into
  # the Rodauth configuration.  Feature is a module subclass, and Feature.define
  # is a class method that creates an instance of Feature (a module) and executes
  # the block in the context of the Feature instance.
  #
  # The second argument is optional, and sets the Feature instance and related
  # FeatureConfiguration instance to a constant in the Rodauth namespace, which
  # makes it easier to locate via inspect.
  Feature.define(:foo, :Foo) do
    # Inside this block, self is an instance of Feature.  As this instance of
    # Feature will be included in the Rodauth::Auth subclass instance if
    # the feature is loaded into the rodauth configuration, methods you define
    # in this block (via def or define_method) will be callable on any
    # rodauth object if this feature is loaded into the rodauth configuration.

    # Feature has many instance methods that define methods in the Feature
    # instance.  This is one of those methods, which sets the text of the notice
    # flash, shown after successful submission of the form. It's basically
    # equivalent to executing this code in the feature:
    #
    #   def foo_notice_flash
    #     "It worked!"
    #   end
    #
    # while also adding a method to the configuration which does:
    #
    #   def foo_notice_flash(v=nil, &block)
    #     block ||= proc{v}
    #     @auth.class_eval do
    #       define_method(:foo_notice_flash, &block)
    #     end
    #   end
    #
    # This is what easily allows you to modify any part of Rodauth during
    # configuration.  The Rodauth::Auth subclass has the default behavior
    # added via a method in an included module (the Feature instance), and the
    # Rodauth::Configuration instance has a method that when called defines
    # a method in the Rodauth::Auth subclass itself, which will take precedence
    # over the default method, which defined in the included Feature instance.
    notice_flash "It worked!"

    # The rest of these method calls are fairly similar to notice_flash.
    # This defines the foo_error_flash method, for the error flash message to
    # show if the form submission wasn't successful.
    error_flash "There was an error"

    # This defines the foo_view method to use template 'foo.str' in the templates
    # folder, and set the title of the page to 'Foo'.
    view 'foo', 'Foo'

    # This defines the foo_additional_form_tags method, which would generally be called
    # inside the foo.str template.
    additional_form_tags

    # This defines the foo_button method, for the text to use on the submit button
    # for the form in foo.str.
    button 'Submit'

    # This defines the foo_redirect method, for where to redirect after successful submission
    # of the form.
    redirect

    # This defines the before_foo method, called before performing the foo action.
    before

    # This defines the after_foo method, called after successfully performing the foo action.
    after

    # This defines a loaded_templates method that calls super and adds 'foo' as one of the
    # templates.  This is necessary for precompilation of templates to work.
    loaded_templates ['foo']

    # This defines the following methods related to sending email:
    #
    # * foo_email_subject: uses given subject
    # * foo_email_body: renders foo-email template
    # * create_foo_email: creates Mail::Message using subject and body
    # * send_foo_email: sends created email
    #
    # The foo-email template should be included in the loaded_templates call to make sure
    # template precompilation works.
    email :foo, 'Foo Subject'

    # auth_value_method is a generic method that takes two arguments, a method to define
    # and a default value.  It is similar to the methods above, except that it allows
    # arbitrary method names.  The notice_flash, error_flash, button, and additional_form_tags
    # methods are actually defined in terms of this method.
    #
    # So this particular method defines a foo_error_status method that will return 401 by
    # default, but also adds a configuration method that allows you to override the default.
    auth_value_method :foo_error_status, 401

    # This is similar to auth_value_method, but it only adds the configuration method.
    # Using this should only be done if you have defining the method in the feature
    # separately (see below).
    auth_value_methods :foo_bar

    # This is similar to auth_value_methods, but it changes the configuration method so that
    # a block is required and you cannot provide an argument.  This is used for the cases
    # where a statically defined value would never make sense, such as when any correct
    # behavior would depend on accessing request-specific information.
    auth_methods :foo

    # route defines a route used for the feature.  This is the code that will be executed
    # if a user goes to /foo in the Roda app.
    route do |r|
      # Inside the block, you are in the context of the Rodauth::Auth subclass instance.
      # r is the Roda::RodaRequest subclass instance, just as it would be for a Roda
      # route block.

      # route adds a before_foo_route method that by default does nothing. It also
      # adds a configuration method that you can call to set behavior that will be
      # executed before routing.
      before_foo_route

      # Just like in Roda, r.get is called for GET requests
      r.get do
        # This will render a view to the user, using the foo.erb template from the
        # templates directory (unless the user has overridden it), inside the Roda
        # application's layout.
        foo_view
      end

      # Just like in Roda, r.post is called for POST requests
      r.post do
        # This is called before performing the foo action
        before_foo

        # This assumes foo returns false or nil on failure, or otherwise on
        # success.
        if foo 
          # In general, Rodauth only calls after_foo if foo is successful.
          after_foo

          # Successful form submission will usually set the notice flash,
          # the redirect to the appropriate page.
          set_notice_flash foo_notice_flash
          redirect foo_redirect
        else
          # Unsucessful form subsmission will usually set the error flash,
          # the redisplay the page so that the submission can be fixed.
          set_error_flash foo_error_flash
          foo_view
        end
      end
    end

    # This is the default behavior for the foo method, if a user doesn't
    # call the foo method inside the configuration block.
    def foo
      # Do Something
    end

    # This is the default behavior for the foo_bar method, if a user doesn't
    # call the foo_bar method inside the configuration block.
    def foo_bar
      42
    end
  end
end