view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    As the name implies "Apache2::Translation" lives mostly in the URI
    Translation Phase. It is somehow similar to "mod_rewrite" but
    configuration statements are read at runtime, thus, allowing to
    reconfigure a server without restarting it.

    The actual configuration statements are read by means of a *Translation
    Provider*, a Perl class offering a particular interface, see below.
    Currently there are 3 providers implemented, Apache2::Translation::DB,
    Apache2::Translation::BDB, and Apache2::Translation::File.

    There is also a WEB interface (Apache2::Translation::Admin).

  An Example
    Let's begin with an example. Given some database table:

     id  key    uri      blk ord action
      1  front  :PRE:    0   0   Cond: $HOSTNAME !~ /^(?:www\.)xyz\.(?:com|de)$/
      2  front  :PRE:    0   1   Redirect: 'http://xyz.com'.$URI, 301
      3  front  :PRE:    1   0   Do: $CTX{lang}='en'
      4  front  :PRE:    1   1   Cond: $HOSTNAME =~ /de$/
      5  front  :PRE:    1   2   Do: $CTX{lang}='de'
      6  front  /static  0   0   File: $DOCROOT.'/'.$CTX{lang}.$MATCHED_PATH_INFO
      7  front  /appl1   0   0   Proxy: 'http://backend/'.$CTX{lang}.$URI
      8  front  /appl2   0   0   Proxy: 'http://backend/'.$URI.'?l='.$CTX{lang}
      9  front  /        0   0   Config: ['AuthName "secret"'], ['AuthType Basic']
     10  back   :PRE:    0   0   Cond: $r->connection->remote_ip ne '127.0.0.1'
     11  back   :PRE:    0   1   Error: 403, 'Forbidden by Apache2::Translation(11)'
     12  back   /appl1   0   0   PerlHandler: 'My::Application1'
     13  back   /appl2   0   0   PerlHandler: 'My::Application2'

    The "id" column in this table is not really necessary for
    "Apache2::Translation". But if you want to deploy
    Apache2::Translation::Admin you need it.

    Well, here we have a frontend/backend configuration. The frontend
    records are labeled with the key "front", the backend records with
    "back".

    When a request comes in first the records with ":PRE:" in the
    "uri"-field are examined. Suppose, a request for
    "http://abc.com/static/img.png" comes in. Record 1 (id=1) checks the
    "Host" header. The expression after "Cond:" is evaluated as Perl code.
    It obviously returns true. "Cond" stands for *condition*. But how does
    it affect the further workflow? Here "blk" and "ord" come in. All
    records with the same "key", "uri" and "blk" form a block. "ord" gives
    an order within this block. Within a block all actions are executed up
    to the first condition that is false.

    Now, because our condition in record 1 is true the action in record 2
    (within the same block) is executed. It redirects the browser with a
    HTTP code of 301 (MOVED PERMANENTLY) to "http://xyz.com/static/img.png".

    When the redirected request comes back the condition in record 1 is
    false. Hence, the next block (key=front, uri=:PRE:, blk=1) is evaluated.
    First a "lang" member of a context hash is set to "en". A "Do" action is
    similar to a condition, only its value is ignored. Record 4 then checks
    if the "Host" header matches "/de$/". If so, then record 5 sets the
    *language* to "de".

    Now, the records labeled with ":PRE:" are finished. The handler starts
    looking for blocks labeled with the request uri. That is, it looks for a
    block with key=front, uri=/static/img.png. None is found.

    Then it cuts off the last part of the uri (/img.png), repeats the lookup
    and finds record 6. The "File" action sets "$r->filename" to
    "$DOCROOT/en/img.png". "Apache2::Translation" provides some convenience
    variables. They are tied to members of the request record.
    $MATCHED_PATH_INFO contains the uri part cut off ("/img.png"). More on
    them below.

    Now another round is started and the next uri part is cut off. Record 9
    matches. We see a "Config" action that sets "AuthName" and "AuthType".

    At the end the translation handler checks if "$r->filename" was set and
    returns "Apache2::Const::OK" or "Apache2::Const::DECLINED" respectively.

    I think that example gives a general idea, what "Apache2::Translation"
    does.

  Processing States
    Internally "Apache2::Translation" is implemented as a state machine. It
    starts in the *START* state, where some variables are initialized. From
    there it shifts immediately to the *PREPOC* state. Here all ":PRE:"
    rules are evaluated. From *PREPROC* it shifts to *PROC*. Now the rules
    with real uris are examined. When the *DONE* state is reached processing
    is finished.

    There is a special state named *LOOKUPFILE*. It is only used for
    subrequests that don't have an URI. For such requests the URI
    translation phase of the request cycle is skipped. Hence a
    *PerlTransHandler* would never be called. Such requests are results of
    calling "$r->lookup_file" for example.

    To catch also such requests install "Apache2::Translation" both as
    *PerlTransHandler* as well as *PerlMapToStorageHandler*. Then if such a
    subrequest occures the handler enters the *LOOKLUPFILE* state instead of
    *PREPROC*. From *LOOKLUPFILE* it normally shifts to *PROC* unless it
    executes a "Restart" action. In that case it shifts to *PREPROC*.

    You have to set $MATCHED_URI to some initial value if you want to hop
    through the *PROC* phase. A still empty $MATCHED_URI shifts from *PROC*
    immediately to *DONE*.

    Note: The *LOOKUPFILE* stuff is still somewhat experimental.

    You can control the current state by means of the "State", "Done" and
    "Restart" actions.

  Blocks and Lists of Blocks
    Above, we have defined a block as all records with the same "key", "uri"
    and "block". The actions within a block are ordered by the "order"
    field.

    A list of blocks is then an ordered list of all blocks with the same
    "key" and "uri". The order is given by the "block" number.

  Actions
    An action starts with a key word optionally followed by a colon and some
    arguments. The key words are case insensitive.

    "Apache2::Translation" provides some environment for code snippets in

README  view on Meta::CPAN

        In detail it installs a "Apache2::Translation::response" as
        "PerlResponseHandler". When called the handler evaluates "string"
        which results either in a subroutine name, a package name, a
        subroutine reference or an object or class that implements the
        "handler" method. If a package name is given it must implement a
        "handler" subroutine.

        If the given package is not yet loaded it is "require"ed.

        Then the resulting subroutine or method is called and $r is passed.

        Further, a "PerlMapToStorageHandler" is installed that skips the
        handling of "Directory" containers and ".htaccess" files. If not
        set, this handler also sets "path_info". Assumed,

         #uri        blk ord action
         /some/path  0   0   PerlHandler: ...

        and a request comes in for "/some/path/foo/bar". Then "path_info" is
        set to "/foo/bar".

    Config: list_of_strings_or_arrays
    FixupConfig: list_of_strings_or_arrays
        Surprisingly, these are the most complex actions of all.

        "Config" adds Apache configuration directives to the request in the
        *Map To Storage* phase before the default "MapToStorage" handler.
        Think of it as a kind of ".htaccess". "FixupConfig" does the same in
        the *Fixup* phase. While "Config" is used quite often "FixupConfig"
        is seldom required. It is used mainly to mend configurations that
        are spoiled by the default "MapToStorage" handler.

        Arguments to both actions are strings or arrays of one or two
        elements:

         Config: 'AuthName "secret"',
                 ['AuthType Basic'],
                 ['ProxyPassReverse http://...', '/path']

        To understand the different meaning, you have to know about how
        Apache applies its configuration to a request. Hence, let's digress
        a little.

        Each Apache directive is used in certain contexts. Some for example
        can occur only in server config context, that means outside any
        "Directory", "Location" or even "VirtualHost" container. "Listen" or
        "PidFile" are examples. Other directives insist on being placed in a
        container.

        Also, the point in time when a directive takes effect differs for
        different directives. "PidFile" is clearly applied during server
        startup before any request is processed. Hence, our "Config" action
        cannot apply "PidFile". It's simply too late. "AllowOverride" is
        applied to single requests. But since it affects the processing of
        ".htaccess" files it must be applied before that processing takes
        place. To make things even more confusing some directives take
        effect at several points in time. Consider

         Options FollowSymLinks ExecCGI

        "FollowSymLinks" is applied when Apache looks up a file in the file
        system, while "ExecCGI" influences the way the response is generated
        ages later.

        Apache solves this complexity by computing a configuration for each
        single request. As a starting point it uses the server default
        configuration. That is the configuration outside any "Location" or
        "Directory" for a virtual host. This basic configuration is assigned
        to the request just between the *Uri Translation Phase* and *Map to
        Storage*. At the very end of *Map to Storage* Apache's core *Map to
        Storage* handler incorporates matching "Directory" containers and
        ".htaccess" files into the request's current configuration.
        "Location" containers are merged after *Map to Storage* is finished.

        Our "Config" action is applied early in *Map to Storage*. That means
        it affects the way Apache maps the request file name computed to the
        file system, because that comes later. But it also means, your
        static configuration (config file based) overrides our "Config"
        actions. This limitation can be partly overcome using "FixupConfig"
        instead of "Config".

        Now, what does the various syntaxes mean? The simplest one:

         #uri      blk ord action
         /uri      0   0   Config: 'ProxyPassReverse http://my.backend.org'

        is very close to

         <Location /uri>
           ProxyPassReverse http://my.backend.org
         </Location>

        Only, it is applied before any "Directory" container takes effect.
        Note, the uri-argument to the "Location" container is the value of
        $MATCHED_URI, see below. This is also valid if the "Config" action
        is used from a "Call"ed block.

        The location uri is sometimes important. "ProxyPassReverse", for
        example, uses the path given to the location container for its own
        purpose.

        All other forms of "Config" are not influenced by $MATCHED_URI.

        These two:

         Config: ['ProxyPassReverse http://my.backend.org']
         Config: ['ProxyPassReverse /path http://my.backend.org', '']

        are equivalent to

         <Location />
           ProxyPassReverse http://my.backend.org
         </Location>

        Note, the location container uri differs.

        The first one of them is also the only form of "Config" available
        with mod_perl before 2.0.3.

        The next one: