=head1 NAME

Toadfarm::Manual::Config - Config file format for Toadfarm

=head1 DESCRIPTION

This manual gives in-depth information about the config file format.

=head2 Basics

The basic structure is a pure Perl file, which defines a hash-ref:

  {
    apps => [],
    hynotoad => {},
    log => {},
    paths => {},
    plugins => [],
    secrets => [],
  };

Anything you put before the hash-ref is up to you.

=head2 Apps

The "apps" key holds a list of application/config pairs. The application can
either be a full path to the application or a class name. The config is either
HTTP headers to trigger on, or L</Special fields>.

The apps are processed in the order they are defined. This means that the
first app that match a given rule will receive the request.

The config example below contain all the special fields that you can use and
a list of example headers to filter on. Each key (except "config") is used
to filter the incoming request, and ALL the specified values must match
for the request to get passed on to a given application.

  {
    apps => {
      "/path/to/myproject/script/myapp" => {

        # special fields
        config => { some_key => "value" },
        local_port => 8080,
        mount_point => "/myapp",
        remote_address => "127.0.0.1",

        # headers
        "Host" => "home.thorsen.pm",
        "User-Agent" => qr{curl},
        "X-Request-Base" => "http://home.thorsen.pm/whatever",
      },
      "Other::App" => {
        # ...
      },
      # ...
    },
    # ...
  };

Example HTTP request that will get sent to "myapp":

  -- Connect (http:home.thorsen.pm:8080)
  -- Client >>> Server (http://home.thorsen.pm/myapp)
  GET /myapp HTTP/1.1
  Connection: keep-alive
  Content-Length: 0
  Accept-Encoding: gzip
  Host: home.thorsen.pm
  User-Agent: curl/7.32.0
  X-Request-Base: http://home.thorsen.pm/whatever

So if "User-Agent" is "Mojolicious (Perl)" instead, but all the other headers
match, then the request will NOT be passed on to "myapp".

Got difficulties getting a request through to an application? Try removing
rules until the request gets through.

=head3 Special fields

Fields that are defined in the list below are special fields.

=over 4

=item * config => \%hash

This config param will override any L<config|Mojolicious/config> parameters
already known in the target application.

Note: These config params are set I<after> L<startup()|Mojolicious/startup>
is called. (This will hopefully be changed/fixed in future release of Toadfarm)

=item * local_port => $str|$regex

Used to only accept requests on a given L<port|Mojo::Transaction/local_port>
access.

=item * mount_point => $str

The default mount point is "/". Setting this to "/foo" will only make the
application accessible under "http://domain.com/foo".

=item * remote_address => $str|$regex

Used to only accept from a given L<address|Mojo::Transaction/remote_address>
access.

=item * X-Request-Base => $str

This header will also set L<request base url|Mojo::URL/base> when this rule
match. This is the same funtionality that is provided by
L<Mojolicious::Plugin::RequestBase>.

=back

Additional fields might be added, but they will always be in lower case.

=head2 Hypnotoad

  {
    hypnotoad => {
      workers => 7,
      listen => ['http://*:8080'],
    },
  }

See L<Mojo::Server::Hypnotoad/SETTINGS> for more options.

=head2 Log

It is possible to get L<Toadfarm> to log for all your apps:

  {
    log => {
      file => '/path/to/log/file.log',
      level => 'debug', # debug, info, warn, ...
      combined => 1,
    },
  }

The trick here is the "combined" flag. It makes all the apps share the same
L<Mojo::Log> object.

=head2 Paths

You can specify custom template and public file paths for Toadfarm. This is
useful if you want your own error templates or serve other assets from
L<Toadfarm>.

  {
    paths => {
      renderer => [ '/my/custom/template/path' ],
      static => [ '/my/custom/static/path' ],
    },
  };

=head2 Plugins

It is possible to load plugins into the core of L<Toadfarm>.

  {
    plugins => [
      "Some::Plugin" => @config_arguments,
    ],
  };

L<Toadfarm> comes with two plugins: L<Toadfarm::Plugin::AccessLog> and
L<Toadfarm::Plugin::Reload>, but you can also use other plugins from
L<CPAN|https://metacpan.org/search?q=Mojolicious%3A%3APlugin>.

=head2 Secrets

Specifying secrets for your app is really important if you are using
L<sesssion|Mojolicious::Controller/session>.

  {
    secrets => ['my super secret'],
  }

See also L<Mojolicious/secrets>.

=head1 AUTHOR

Jan Henning Thorsen - C<jhthorsen@cpan.org>

=cut