view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      # export our provider parameters
      <Location /config>
        SetHandler modperl
        PerlResponseHandler Apache2::Translation::Config
      </Location>

      # configuring the WEB interface
      PerlModule Apache2::Translation::Admin
      <Location /-/transadm/>
        SetHandler modperl
        PerlResponseHandler Apache2::Translation::Admin
      </Location>

INSTALLATION
     perl Makefile.PL
     make
     make test
     make install

DESCRIPTION
    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
    actions. They are compiled into perl functions. The compiled result is
    cached. 2 variables, $r and %CTX, are provided plus a few convenience
    variables. $r is the current "Apache2::RequestRec". %CTX is a hash that
    can be used to store arbitrary data. This hash is not used by
    Apache2::Translation itself. It can be used to pass data between
    actions. But note, the hash is localized to the translation handler. So,
    it cannot be used to pass data between different phases of the apache