Initial class construction
This commit is contained in:
João Narciso
528
Git/usr/share/perl5/vendor_perl/HTTP/Negotiate.pm
Normal file
528
Git/usr/share/perl5/vendor_perl/HTTP/Negotiate.pm
Normal file
@ -0,0 +1,528 @@
|
||||
package HTTP::Negotiate;
|
||||
|
||||
$VERSION = "6.01";
|
||||
sub Version { $VERSION; }
|
||||
|
||||
require Exporter;
|
||||
@ISA = qw(Exporter);
|
||||
@EXPORT = qw(choose);
|
||||
|
||||
require HTTP::Headers;
|
||||
|
||||
$DEBUG = 0;
|
||||
|
||||
sub choose ($;$)
|
||||
{
|
||||
my($variants, $request) = @_;
|
||||
my(%accept);
|
||||
|
||||
unless (defined $request) {
|
||||
# Create a request object from the CGI environment variables
|
||||
$request = HTTP::Headers->new;
|
||||
$request->header('Accept', $ENV{HTTP_ACCEPT})
|
||||
if $ENV{HTTP_ACCEPT};
|
||||
$request->header('Accept-Charset', $ENV{HTTP_ACCEPT_CHARSET})
|
||||
if $ENV{HTTP_ACCEPT_CHARSET};
|
||||
$request->header('Accept-Encoding', $ENV{HTTP_ACCEPT_ENCODING})
|
||||
if $ENV{HTTP_ACCEPT_ENCODING};
|
||||
$request->header('Accept-Language', $ENV{HTTP_ACCEPT_LANGUAGE})
|
||||
if $ENV{HTTP_ACCEPT_LANGUAGE};
|
||||
}
|
||||
|
||||
# Get all Accept values from the request. Build a hash initialized
|
||||
# like this:
|
||||
#
|
||||
# %accept = ( type => { 'audio/*' => { q => 0.2, mbx => 20000 },
|
||||
# 'audio/basic' => { q => 1 },
|
||||
# },
|
||||
# language => { 'no' => { q => 1 },
|
||||
# }
|
||||
# );
|
||||
|
||||
$request->scan(sub {
|
||||
my($key, $val) = @_;
|
||||
|
||||
my $type;
|
||||
if ($key =~ s/^Accept-//) {
|
||||
$type = lc($key);
|
||||
}
|
||||
elsif ($key eq "Accept") {
|
||||
$type = "type";
|
||||
}
|
||||
else {
|
||||
return;
|
||||
}
|
||||
|
||||
$val =~ s/\s+//g;
|
||||
my $default_q = 1;
|
||||
for my $name (split(/,/, $val)) {
|
||||
my(%param, $param);
|
||||
if ($name =~ s/;(.*)//) {
|
||||
for $param (split(/;/, $1)) {
|
||||
my ($pk, $pv) = split(/=/, $param, 2);
|
||||
$param{lc $pk} = $pv;
|
||||
}
|
||||
}
|
||||
$name = lc $name;
|
||||
if (defined $param{'q'}) {
|
||||
$param{'q'} = 1 if $param{'q'} > 1;
|
||||
$param{'q'} = 0 if $param{'q'} < 0;
|
||||
}
|
||||
else {
|
||||
$param{'q'} = $default_q;
|
||||
|
||||
# This makes sure that the first ones are slightly better off
|
||||
# and therefore more likely to be chosen.
|
||||
$default_q -= 0.0001;
|
||||
}
|
||||
$accept{$type}{$name} = \%param;
|
||||
}
|
||||
});
|
||||
|
||||
# Check if any of the variants specify a language. We do this
|
||||
# because it influences how we treat those without (they default to
|
||||
# 0.5 instead of 1).
|
||||
my $any_lang = 0;
|
||||
for $var (@$variants) {
|
||||
if ($var->[5]) {
|
||||
$any_lang = 1;
|
||||
last;
|
||||
}
|
||||
}
|
||||
|
||||
if ($DEBUG) {
|
||||
print "Negotiation parameters in the request\n";
|
||||
for $type (keys %accept) {
|
||||
print " $type:\n";
|
||||
for $name (keys %{$accept{$type}}) {
|
||||
print " $name\n";
|
||||
for $pv (keys %{$accept{$type}{$name}}) {
|
||||
print " $pv = $accept{$type}{$name}{$pv}\n";
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
my @Q = (); # This is where we collect the results of the
|
||||
# quality calculations
|
||||
|
||||
# Calculate quality for all the variants that are available.
|
||||
for (@$variants) {
|
||||
my($id, $qs, $ct, $enc, $cs, $lang, $bs) = @$_;
|
||||
$qs = 1 unless defined $qs;
|
||||
$ct = '' unless defined $ct;
|
||||
$bs = 0 unless defined $bs;
|
||||
$lang = lc($lang) if $lang; # lg tags are always case-insensitive
|
||||
if ($DEBUG) {
|
||||
print "\nEvaluating $id (ct='$ct')\n";
|
||||
printf " qs = %.3f\n", $qs;
|
||||
print " enc = $enc\n" if $enc && !ref($enc);
|
||||
print " enc = @$enc\n" if $enc && ref($enc);
|
||||
print " cs = $cs\n" if $cs;
|
||||
print " lang = $lang\n" if $lang;
|
||||
print " bs = $bs\n" if $bs;
|
||||
}
|
||||
|
||||
# Calculate encoding quality
|
||||
my $qe = 1;
|
||||
# If the variant has no assigned Content-Encoding, or if no
|
||||
# Accept-Encoding field is present, then the value assigned
|
||||
# is "qe=1". If *all* of the variant's content encodings
|
||||
# are listed in the Accept-Encoding field, then the value
|
||||
# assigned is "qw=1". If *any* of the variant's content
|
||||
# encodings are not listed in the provided Accept-Encoding
|
||||
# field, then the value assigned is "qe=0"
|
||||
if (exists $accept{'encoding'} && $enc) {
|
||||
my @enc = ref($enc) ? @$enc : ($enc);
|
||||
for (@enc) {
|
||||
print "Is encoding $_ accepted? " if $DEBUG;
|
||||
unless(exists $accept{'encoding'}{$_}) {
|
||||
print "no\n" if $DEBUG;
|
||||
$qe = 0;
|
||||
last;
|
||||
}
|
||||
else {
|
||||
print "yes\n" if $DEBUG;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Calculate charset quality
|
||||
my $qc = 1;
|
||||
# If the variant's media-type has no charset parameter,
|
||||
# or the variant's charset is US-ASCII, or if no Accept-Charset
|
||||
# field is present, then the value assigned is "qc=1". If the
|
||||
# variant's charset is listed in the Accept-Charset field,
|
||||
# then the value assigned is "qc=1. Otherwise, if the variant's
|
||||
# charset is not listed in the provided Accept-Encoding field,
|
||||
# then the value assigned is "qc=0".
|
||||
if (exists $accept{'charset'} && $cs && $cs ne 'us-ascii' ) {
|
||||
$qc = 0 unless $accept{'charset'}{$cs};
|
||||
}
|
||||
|
||||
# Calculate language quality
|
||||
my $ql = 1;
|
||||
if ($lang && exists $accept{'language'}) {
|
||||
my @lang = ref($lang) ? @$lang : ($lang);
|
||||
# If any of the variant's content languages are listed
|
||||
# in the Accept-Language field, the the value assigned is
|
||||
# the largest of the "q" parameter values for those language
|
||||
# tags.
|
||||
my $q = undef;
|
||||
for (@lang) {
|
||||
next unless exists $accept{'language'}{$_};
|
||||
my $this_q = $accept{'language'}{$_}{'q'};
|
||||
$q = $this_q unless defined $q;
|
||||
$q = $this_q if $this_q > $q;
|
||||
}
|
||||
if(defined $q) {
|
||||
$DEBUG and print " -- Exact language match at q=$q\n";
|
||||
}
|
||||
else {
|
||||
# If there was no exact match and at least one of
|
||||
# the Accept-Language field values is a complete
|
||||
# subtag prefix of the content language tag(s), then
|
||||
# the "q" parameter value of the largest matching
|
||||
# prefix is used.
|
||||
$DEBUG and print " -- No exact language match\n";
|
||||
my $selected = undef;
|
||||
for $al (keys %{ $accept{'language'} }) {
|
||||
if (index($al, "$lang-") == 0) {
|
||||
# $lang starting with $al isn't enough, or else
|
||||
# Accept-Language: hu (Hungarian) would seem
|
||||
# to accept a document in hup (Hupa)
|
||||
$DEBUG and print " -- $al ISA $lang\n";
|
||||
$selected = $al unless defined $selected;
|
||||
$selected = $al if length($al) > length($selected);
|
||||
}
|
||||
else {
|
||||
$DEBUG and print " -- $lang isn't a $al\n";
|
||||
}
|
||||
}
|
||||
$q = $accept{'language'}{$selected}{'q'} if $selected;
|
||||
|
||||
# If none of the variant's content language tags or
|
||||
# tag prefixes are listed in the provided
|
||||
# Accept-Language field, then the value assigned
|
||||
# is "ql=0.001"
|
||||
$q = 0.001 unless defined $q;
|
||||
}
|
||||
$ql = $q;
|
||||
}
|
||||
else {
|
||||
$ql = 0.5 if $any_lang && exists $accept{'language'};
|
||||
}
|
||||
|
||||
my $q = 1;
|
||||
my $mbx = undef;
|
||||
# If no Accept field is given, then the value assigned is "q=1".
|
||||
# If at least one listed media range matches the variant's media
|
||||
# type, then the "q" parameter value assigned to the most specific
|
||||
# of those matched is used (e.g. "text/html;version=3.0" is more
|
||||
# specific than "text/html", which is more specific than "text/*",
|
||||
# which in turn is more specific than "*/*"). If not media range
|
||||
# in the provided Accept field matches the variant's media type,
|
||||
# then the value assigned is "q=0".
|
||||
if (exists $accept{'type'} && $ct) {
|
||||
# First we clean up our content-type
|
||||
$ct =~ s/\s+//g;
|
||||
my $params = "";
|
||||
$params = $1 if $ct =~ s/;(.*)//;
|
||||
my($type, $subtype) = split("/", $ct, 2);
|
||||
my %param = ();
|
||||
for $param (split(/;/, $params)) {
|
||||
my($pk,$pv) = split(/=/, $param, 2);
|
||||
$param{$pk} = $pv;
|
||||
}
|
||||
|
||||
my $sel_q = undef;
|
||||
my $sel_mbx = undef;
|
||||
my $sel_specificness = 0;
|
||||
|
||||
ACCEPT_TYPE:
|
||||
for $at (keys %{ $accept{'type'} }) {
|
||||
print "Consider $at...\n" if $DEBUG;
|
||||
my($at_type, $at_subtype) = split("/", $at, 2);
|
||||
# Is it a match on the type
|
||||
next if $at_type ne '*' && $at_type ne $type;
|
||||
next if $at_subtype ne '*' && $at_subtype ne $subtype;
|
||||
my $specificness = 0;
|
||||
$specificness++ if $at_type ne '*';
|
||||
$specificness++ if $at_subtype ne '*';
|
||||
# Let's see if content-type parameters also match
|
||||
while (($pk, $pv) = each %param) {
|
||||
print "Check if $pk = $pv is true\n" if $DEBUG;
|
||||
next unless exists $accept{'type'}{$at}{$pk};
|
||||
next ACCEPT_TYPE
|
||||
unless $accept{'type'}{$at}{$pk} eq $pv;
|
||||
print "yes it is!!\n" if $DEBUG;
|
||||
$specificness++;
|
||||
}
|
||||
print "Hurray, type match with specificness = $specificness\n"
|
||||
if $DEBUG;
|
||||
|
||||
if (!defined($sel_q) || $sel_specificness < $specificness) {
|
||||
$sel_q = $accept{'type'}{$at}{'q'};
|
||||
$sel_mbx = $accept{'type'}{$at}{'mbx'};
|
||||
$sel_specificness = $specificness;
|
||||
}
|
||||
}
|
||||
$q = $sel_q || 0;
|
||||
$mbx = $sel_mbx;
|
||||
}
|
||||
|
||||
my $Q;
|
||||
if (!defined($mbx) || $mbx >= $bs) {
|
||||
$Q = $qs * $qe * $qc * $ql * $q;
|
||||
}
|
||||
else {
|
||||
$Q = 0;
|
||||
print "Variant's size is too large ==> Q=0\n" if $DEBUG;
|
||||
}
|
||||
|
||||
if ($DEBUG) {
|
||||
$mbx = "undef" unless defined $mbx;
|
||||
printf "Q=%.4f", $Q;
|
||||
print " (q=$q, mbx=$mbx, qe=$qe, qc=$qc, ql=$ql, qs=$qs)\n";
|
||||
}
|
||||
|
||||
push(@Q, [$id, $Q, $bs]);
|
||||
}
|
||||
|
||||
|
||||
@Q = sort { $b->[1] <=> $a->[1] || $a->[2] <=> $b->[2] } @Q;
|
||||
|
||||
return @Q if wantarray;
|
||||
return undef unless @Q;
|
||||
return undef if $Q[0][1] == 0;
|
||||
$Q[0][0];
|
||||
}
|
||||
|
||||
1;
|
||||
|
||||
__END__
|
||||
|
||||
|
||||
=head1 NAME
|
||||
|
||||
HTTP::Negotiate - choose a variant to serve
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
use HTTP::Negotiate qw(choose);
|
||||
|
||||
# ID QS Content-Type Encoding Char-Set Lang Size
|
||||
$variants =
|
||||
[['var1', 1.000, 'text/html', undef, 'iso-8859-1', 'en', 3000],
|
||||
['var2', 0.950, 'text/plain', 'gzip', 'us-ascii', 'no', 400],
|
||||
['var3', 0.3, 'image/gif', undef, undef, undef, 43555],
|
||||
];
|
||||
|
||||
@preferred = choose($variants, $request_headers);
|
||||
$the_one = choose($variants);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This module provides a complete implementation of the HTTP content
|
||||
negotiation algorithm specified in F<draft-ietf-http-v11-spec-00.ps>
|
||||
chapter 12. Content negotiation allows for the selection of a
|
||||
preferred content representation based upon attributes of the
|
||||
negotiable variants and the value of the various Accept* header fields
|
||||
in the request.
|
||||
|
||||
The variants are ordered by preference by calling the function
|
||||
choose().
|
||||
|
||||
The first parameter is reference to an array of the variants to
|
||||
choose among.
|
||||
Each element in this array is an array with the values [$id, $qs,
|
||||
$content_type, $content_encoding, $charset, $content_language,
|
||||
$content_length] whose meanings are described
|
||||
below. The $content_encoding and $content_language can be either a
|
||||
single scalar value or an array reference if there are several values.
|
||||
|
||||
The second optional parameter is either a HTTP::Headers or a HTTP::Request
|
||||
object which is searched for "Accept*" headers. If this
|
||||
parameter is missing, then the accept specification is initialized
|
||||
from the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
|
||||
HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.
|
||||
|
||||
In an array context, choose() returns a list of [variant
|
||||
identifier, calculated quality, size] tuples. The values are sorted by
|
||||
quality, highest quality first. If the calculated quality is the same
|
||||
for two variants, then they are sorted by size (smallest first). I<E.g.>:
|
||||
|
||||
(['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
|
||||
|
||||
Note that also zero quality variants are included in the return list
|
||||
even if these should never be served to the client.
|
||||
|
||||
In a scalar context, it returns the identifier of the variant with the
|
||||
highest score or C<undef> if none have non-zero quality.
|
||||
|
||||
If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of
|
||||
noise is generated on STDOUT during evaluation of choose().
|
||||
|
||||
=head1 VARIANTS
|
||||
|
||||
A variant is described by a list of the following values. If the
|
||||
attribute does not make sense or is unknown for a variant, then use
|
||||
C<undef> instead.
|
||||
|
||||
=over 3
|
||||
|
||||
=item identifier
|
||||
|
||||
This is a string that you use as the name for the variant. This
|
||||
identifier for the preferred variants returned by choose().
|
||||
|
||||
=item qs
|
||||
|
||||
This is a number between 0.000 and 1.000 that describes the "source
|
||||
quality". This is what F<draft-ietf-http-v11-spec-00.ps> says about this
|
||||
value:
|
||||
|
||||
Source quality is measured by the content provider as representing the
|
||||
amount of degradation from the original source. For example, a
|
||||
picture in JPEG form would have a lower qs when translated to the XBM
|
||||
format, and much lower qs when translated to an ASCII-art
|
||||
representation. Note, however, that this is a function of the source
|
||||
- an original piece of ASCII-art may degrade in quality if it is
|
||||
captured in JPEG form. The qs values should be assigned to each
|
||||
variant by the content provider; if no qs value has been assigned, the
|
||||
default is generally "qs=1".
|
||||
|
||||
=item content-type
|
||||
|
||||
This is the media type of the variant. The media type does not
|
||||
include a charset attribute, but might contain other parameters.
|
||||
Examples are:
|
||||
|
||||
text/html
|
||||
text/html;version=2.0
|
||||
text/plain
|
||||
image/gif
|
||||
image/jpg
|
||||
|
||||
=item content-encoding
|
||||
|
||||
This is one or more content encodings that has been applied to the
|
||||
variant. The content encoding is generally used as a modifier to the
|
||||
content media type. The most common content encodings are:
|
||||
|
||||
gzip
|
||||
compress
|
||||
|
||||
=item content-charset
|
||||
|
||||
This is the character set used when the variant contains text.
|
||||
The charset value should generally be C<undef> or one of these:
|
||||
|
||||
us-ascii
|
||||
iso-8859-1 ... iso-8859-9
|
||||
iso-2022-jp
|
||||
iso-2022-jp-2
|
||||
iso-2022-kr
|
||||
unicode-1-1
|
||||
unicode-1-1-utf-7
|
||||
unicode-1-1-utf-8
|
||||
|
||||
=item content-language
|
||||
|
||||
This describes one or more languages that are used in the variant.
|
||||
Language is described like this in F<draft-ietf-http-v11-spec-00.ps>: A
|
||||
language is in this context a natural language spoken, written, or
|
||||
otherwise conveyed by human beings for communication of information to
|
||||
other human beings. Computer languages are explicitly excluded.
|
||||
|
||||
The language tags are defined by RFC 3066. Examples
|
||||
are:
|
||||
|
||||
no Norwegian
|
||||
en International English
|
||||
en-US US English
|
||||
en-cockney
|
||||
|
||||
=item content-length
|
||||
|
||||
This is the number of bytes used to represent the content.
|
||||
|
||||
=back
|
||||
|
||||
=head1 ACCEPT HEADERS
|
||||
|
||||
The following Accept* headers can be used for describing content
|
||||
preferences in a request (This description is an edited extract from
|
||||
F<draft-ietf-http-v11-spec-00.ps>):
|
||||
|
||||
=over 3
|
||||
|
||||
=item Accept
|
||||
|
||||
This header can be used to indicate a list of media ranges which are
|
||||
acceptable as a response to the request. The "*" character is used to
|
||||
group media types into ranges, with "*/*" indicating all media types
|
||||
and "type/*" indicating all subtypes of that type.
|
||||
|
||||
The parameter q is used to indicate the quality factor, which
|
||||
represents the user's preference for that range of media types. The
|
||||
parameter mbx gives the maximum acceptable size of the response
|
||||
content. The default values are: q=1 and mbx=infinity. If no Accept
|
||||
header is present, then the client accepts all media types with q=1.
|
||||
|
||||
For example:
|
||||
|
||||
Accept: audio/*;q=0.2;mbx=200000, audio/basic
|
||||
|
||||
would mean: "I prefer audio/basic (of any size), but send me any audio
|
||||
type if it is the best available after an 80% mark-down in quality and
|
||||
its size is less than 200000 bytes"
|
||||
|
||||
|
||||
=item Accept-Charset
|
||||
|
||||
Used to indicate what character sets are acceptable for the response.
|
||||
The "us-ascii" character set is assumed to be acceptable for all user
|
||||
agents. If no Accept-Charset field is given, the default is that any
|
||||
charset is acceptable. Example:
|
||||
|
||||
Accept-Charset: iso-8859-1, unicode-1-1
|
||||
|
||||
|
||||
=item Accept-Encoding
|
||||
|
||||
Restricts the Content-Encoding values which are acceptable in the
|
||||
response. If no Accept-Encoding field is present, the server may
|
||||
assume that the client will accept any content encoding. An empty
|
||||
Accept-Encoding means that no content encoding is acceptable. Example:
|
||||
|
||||
Accept-Encoding: compress, gzip
|
||||
|
||||
|
||||
=item Accept-Language
|
||||
|
||||
This field is similar to Accept, but restricts the set of natural
|
||||
languages that are preferred in a response. Each language may be
|
||||
given an associated quality value which represents an estimate of the
|
||||
user's comprehension of that language. For example:
|
||||
|
||||
Accept-Language: no, en-gb;q=0.8, de;q=0.55
|
||||
|
||||
would mean: "I prefer Norwegian, but will accept British English (with
|
||||
80% comprehension) or German (with 55% comprehension).
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 1996,2001 Gisle Aas.
|
||||
|
||||
This library is free software; you can redistribute it and/or
|
||||
modify it under the same terms as Perl itself.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Gisle Aas <gisle@aas.no>
|
||||
|
||||
=cut
|
||||
Reference in New Issue
Block a user