NAME

Leyland::Negotiator - Performs HTTP negotiations for Leyland requests

VERSION

version 0.001007

SYNOPSIS

        # used internally

DESCRIPTION

This module performs HTTP negotiations for Leyland requests. When a request is handled by a Leyland application, it is first negotiated by this module to make sure it can be handled, and to decide on how to handle it.

The following negotiations are performed:

1. Character set negotiation - Leyland only supports UTF-8, so if the request defines a different character set, a 400 Bad Request error is thrown.
2. Path negotiation - The request path is compared against the application's routes, and a list of routes is created. If none are found, a 404 Not Found error is thrown.
3. Request method negotiation - The list of routes is filtered by the request method (GET, POST, etc.), so only routes of this method remain. If none remain, a 405 Method Not Allowed error is thrown.
4. Received content type negotiation - The list of routes is filtered by the request content type (text/html for example), if it has any, so only routes that accept this media type remain. If none remain, a 415 Unsupported Media Type error is thrown.
5. Returned content type negotiation - The list of routes is filtered by the request accepted media types (residing in the Accept HTTP header), if defined, so only routes that return a media type accepted by the client remain. If none remain, a 406 Not Acceptable error is thrown.

There's one thing this method doesn't perform, and that's language negotiation. Since proper HTTP language negotiation is rare (and difficult to implement), you are expect to perform that yourself (only if you wish, of course). For that, Leyland::Localizer is provided.

This module also finds routes that match a path when an HTTP OPTIONS request is received.

CLASS METHODS

negotiate( $c, $app_routes, $path )

Performs a series of HTTP negotiations on the request and returns matching routes. If none are found, an error is thrown. See "DESCRIPTION" for more information.

find_options( $c, $app_routes )

Finds all routes that match a certain path when an HTTP OPTIONS request is received.

method_name( $meth )

Receives the name of a Leyland-style HTTP method (like 'get', 'post', 'put' or 'del') and returns the correct HTTP name of it (like 'GET', 'POST', 'PUT' or 'DELETE').

INTERNAL METHODS

The following methods are only to be used internally.

_negotiate_path( $c, \%args )

_prefs_and_routes( $path )

_matching_routes( $app_routes, $pref_routes, $internal )

_negotiate_method( $method, $routes )

_negotiate_receive_media( $c, $all_routes )

_negotiate_return_media( $c, $all_routes )

_negotiate_charset( $c )

AUTHOR

Ido Perlmuter, <ido at ido50.net>

BUGS

Please report any bugs or feature requests to bug-Leyland at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Leyland. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

        perldoc Leyland::Negotiator

You can also look for information at:

RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Leyland
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Leyland
CPAN Ratings
http://cpanratings.perl.org/d/Leyland
Search CPAN
http://search.cpan.org/dist/Leyland/

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.