view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        response. However, if you call "respond" on this context again an
        error will logged. The second response will not be sent (it can't be
        since the connection is probably already closed).

        If you wish to stop processing after sending the response, you can
        "die" with the result from "respond" since it returns a special
        object for this purpose:

            die $c->respond({ a => 1, });

        See the EXCEPTIONS section for more details on the use of exceptions
        in Chouette.

        "respond" takes an optional second argument which is the HTTP
        response code (defaults to 200):

            $c->respond({ error => "access denied" }, 403);

        Note that processing continues here also. If you wish to terminate
        the processing right away, prefix with "die" as above, or use the
        following shortcut:

            die "403: access denied";

        The client will receive an HTTP response with the Feersum default
        message ("Forbidden" in this case) and the JSON body will be
        "{"error":"access denied"}".

        This works too, except the value of "error" in the JSON body of the
        response will just be "HTTP code 403":

            die 403;

    "done"
        If you wish to stop processing but not send a response:

            $c->done;

        You will need to send a response later, usually from an async
        callback. Note: If the last reference to the context is destroyed
        without a response being sent, the message "no response was sent,
        sending 500" will be logged and a 500 "internal server error"
        response will be sent.

        You don't ever need to call "done". You can just "return" from the
        handler instead. "done" is only for convenience in case you are
        deeply nested in callbacks and don't want to worry about writing a
        bunch of nested returns.

    "respond_raw"
        Similar to "respond" except it doesn't assume JSON encoding:

            $c->respond_raw(200, 'text/plain', 'here is some plain text');

    "logger"
        Returns the Log::Defer object associated with the request:

            $c->logger->info("some stuff is happening");

            {
                my $timer = $c->logger->timer('doing big_computation');
                big_computation();
            }

        See the Log::Defer docs for more details. For viewing the log
        messages, check out Log::Defer::Viz.

    "config"
        Returns the "config" hash. See the "CHOUETTE OBJECT" section for
        details.

    "req"
        Returns the Plack::Request object created for this request.

            my $name = $c->req->parameters->{name};

    "res"
        One would think this would return a Plack::Response object.
        Unfortunately this isn't yet implemented and will instead throw an
        error.

    "generate_token"
        Generates a random string using a default-config Session::Token
        generator. The generator is created when the first token is needed
        so as to avoid a "cold" entropy pool immediately after a reboot (see
        the Session::Token docs).

    "task"
        Returns an AnyEvent::Task checkout object for the task with the
        given name:

            $c->task('db')->selectrow_hashref(q{ SELECT * FROM sometable WHERE id = ? },
                                              undef, $id, sub {
                my ($dbh, $row) = @_;

                die $c->respond($row);
            });

        Checkout options can be passed after the task name:

            $c->task('db', timeout => 5)->selectrow_hashref(...);

        See AnyEvent::Task for more details.

EXCEPTIONS
    Assuming you are familiar with asynchronous programming, most of
    Chouette should feel straightforward. The only thing that might be
    unfamiliar is how exceptions are used.

  ERROR HANDLING
    The first unusual thing about how Chouette uses exceptions is that it
    uses them for error conditions, in contrast to many other asynchronous
    frameworks.

    Most asynchronous frameworks are unable to use exceptions to signal
    errors since an error may occur in a callback being run from the event
    loop. If this callback throws an exception, there will be nothing to
    catch it, except perhaps a catch block installed by the event loop. Even
    if the event loop does catch it, it won't know which connection the
    exception is for, and therefore won't be able to send a 500 error to
    that connection or add a message to that connection's log.