internals.rdoc

doc/guides/internals.rdoc
Last Update: 2022-03-09 12:26:27 -0800

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