view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Chouette - REST API Framework

DESCRIPTION
    Chouette is a framework for making asynchronous HTTP services. It makes
    some opinionated design choices, but is otherwise fairly flexible.

    AnyEvent is used as the glue to connect all the asynchronous libraries,
    although Chouette depends on Feersum and therefore EV for its event
    loop. It uses Feersum in PSGI mode so it can use Plack for request
    parsing, and has support for Plack::Middleware wrappers. Feersum is the
    least conservative choice in the stack but there aren't very many
    alternatives (Twiggy is a possibility but it is somewhat buggy and you
    need a hack to use unix sockets).

    Chouette generally assumes that its input will be
    "application/x-www-form-urlencoded". Plack::Request::WithEncoding is
    used so that text is properly decoded (we recommend UTF-8 of course).
    For output, the default is "application/json" encoded with JSON::XS.
    Both the input and output types can be modified, although this is only
    partially documented so far.

    Chouette apps can optionally load a config file and its format is
    "YAML", loaded with the YAML module. Regexp::Assemble is used for
    efficient route-dispatch.

    The above aside, Chouette's main purpose is to glue together several of
    my own modules into a cohesive whole. These modules have been designed
    to work together and I have used them to build numerous services, some
    of which handle a considerable amount of traffic and/or have very
    complicated requirements.

    Chouette was extracted from some of these services I have built before,
    and I have put in the extra effort required so that all the modules work
    together in the ways they were designed:

    AnyEvent::Task
        Allows us to perform blocking operations without holding up other
        requests.

    Callback::Frame
        Makes exception handling simple and convenient. You can "die"
        anywhere and it will only affect the request being currently
        handled.

        Important note: If you are using 3rd-party libraries that accept
        callbacks, please understand how Callback::Frame works. You will
        usually need to pass "fub {}" instead of "sub {}" to these
        libraries. See the EXCEPTIONS section for more details.

    Session::Token
        For random identifiers such as session tokens (obviously).

    Log::Defer
        Structured logging, properly integrated with AnyEvent::Task so your
        tasks can log messages into the proper request log contexts.

        Note that Chouette also depends on Log::Defer::Viz so
        "log-defer-viz" will be available for viewing logs.

    Log::File::Rolling
        Store logs in files and rotate them periodically. Also maintains a
        current symlink so you can simply run the following in a shell and
        you'll always see the latest logs as you need them:

            $ log-defer-viz -F /var/myapi/logs/myapi.current.log

    Chouette will always depend on AnyEvent::Task, Callback::Frame,
    Session::Token, and Log::Defer so if your app also uses these modules
    then it is sufficient to depend on "Chouette" alone.

    Where does the name "Chouette" come from? A chouette
    <http://www.bkgm.com/variants/Chouette.html> is a multi-player,
    fast-paced backgammon game with lots of stuff going on at once, kind of
    like an asynchronous REST API server... Hmmm, a bit of a stretch isn't
    it? To be honest it's just a cool name and I love backgammon, especially
    chouettes with friends and beer. :)