view release on metacpan or  search on metacpan

lib/Apache2/API/Status.pm  view on Meta::CPAN

        421 => "錯誤定向的請求",
        422 => "無法處理的實體！",
        423 => "資源已鎖定！",
        424 => "相依關係失敗！",
        425 => "時機過早！",
        426 => "需要升級！",
        428 => "需要先決條件",
        429 => "請求過多！",
        431 => "請求標頭欄位過大！",
        444 => "連接關閉而沒有響應",
        451 => "因法律因素無法提供！",
        499 => "用戶端關閉請求",
        500 => "伺服器錯誤！",
        501 => "無法執行請求！",
        502 => "閘道器錯誤！",
        503 => "服務不可用！",
        504 => "閘道逾時！",
        505 => "不支持HTTP版本",
        506 => "變體也會變化！",
        507 => "儲存空間不足！",
        508 => "偵測到循環！",
        509 => "超過帶寬限制",
        510 => "未擴展",
        511 => "需要網路驗證",
        599 => "網絡連接超時錯誤",
    },
};
our $MAP_LANG_SHORT =
{
de		=> 'de_DE',
en		=> 'en_GB',
fr		=> 'fr_FR',
it		=> 'it_IT',
ja		=> 'ja_JP',
ko      => 'ko_KR',
nl      => 'nl_NL',
pl      => 'pl_PL',
pt      => 'pt_PT',
ro      => 'ro_RO',
ru      => 'ru_RU',
'tr'    => 'tr_TR',
zh		=> 'zh_TW',
};

# So that querying the hash directly with $HTTP_CODES->{ja} works too
foreach my $lang ( keys( %$MAP_LANG_SHORT ) )
{
    $HTTP_CODES->{ $lang } = $HTTP_CODES->{ $MAP_LANG_SHORT->{ $lang } };
}

our $STATUS_TO_TYPE =
{
    301 => "moved_permanently",
    302 => "moved_temporarily",
    307 => "redirect_temporarily",
    308 => "redirect_permanent",
    400 => "bad_request",
    401 => "unauthorized",
    402 => "payment_required",
    403 => "forbidden",
    404 => "not_found",
    405 => "method_not_allowed",
    406 => "not_acceptable",
    407 => "proxy_authentication_required",
    408 => "request_time_out",
    409 => "conflict",
    410 => "gone",
    411 => "length_required",
    412 => "precondition_failed",
    413 => "request_entity_too_large",
    414 => "request_uri_too_large",
    415 => "unsupported_media_type",
    416 => "range_not_satisfiable",
    417 => "expectation_failed",
    422 => "unprocessable_entity",
    423 => "locked",
    424 => "failed_dependency",
    425 => "too_early",
    426 => "upgrade_required",
    429 => "too_many_requests",
    431 => "request_header_fields_too_large",
    451 => "unavailable_for_legal_reasons",
    500 => "internal_server_error",
    501 => "not_implemented",
    502 => "bad_gateway",
    503 => "service_unavailable",
    504 => "gateway_timeout",
    505 => "http_version_not_supported",
    506 => "variant_also_varies",
    507 => "insufficient_storage",
    508 => "loop_detected",
};

# Missing constants in Apache2::Const
my $additions =
{
103 => 'EARLY_HINTS',
418 => 'I_AM_A_TEA_POT',
421 => 'MISDIRECTED_REQUEST',
425 => 'TOO_EARLY',
444 => 'CONNECTION_CLOSED_WITHOUT_RESPONSE',
451 => 'UNAVAILABLE_FOR_LEGAL_REASONS',
499 => 'CLIENT_CLOSED_REQUEST',
505 => 'HTTP_VERSION_NOT_SUPPORTED',
509 => 'BANDWIDTH_LIMIT_EXCEEDED',
599 => 'NETWORK_CONNECT_TIMEOUT_ERROR',
};

foreach my $code ( keys( %$additions ) )
{
    unless( Apache2::Const->can( $additions->{ $code } ) )
    {
        eval( "*Apache2::Const::" . $additions->{ $code } . " = sub{$code};" );
        warn( "Error adding Apache2::Const for HTTP code $code: $@" ) if( $@ );
    }
}

sub init
{
    my $self = shift( @_ );
    my $r = shift( @_ );
    $self->SUPER::init( @_ );
    return( $self );
}

sub convert_short_lang_to_long
{
	my $self = shift( @_ );
	my $lang = shift( @_ );
	# Nothing to do; we already have a good value
	return( $lang ) if( $lang =~ /^[a-z]{2}_[A-Z]{2}$/ );
	return( $MAP_LANG_SHORT->{ lc( $lang ) } ) if( CORE::exists( $MAP_LANG_SHORT->{ lc( $lang ) } ) );
	return( '' );
}

sub is_cacheable_by_default
{
    my $self = shift( @_ );
    my $code = shift( @_ );
    return( $self->error( "A 3 digit code is required." ) ) if( !defined( $code ) || $code !~ /^\d{3}$/ );
    return(
           $code == 200 # OK
        || $code == 203 # Non-Authoritative Information
        || $code == 204 # No Content
        || $code == 206 # Not Acceptable
        || $code == 300 # Multiple Choices
        || $code == 301 # Moved Permanently
        || $code == 308 # Permanent Redirect

lib/Apache2/API/Status.pm  view on Meta::CPAN

It provides a full set of constants to use and import.

Finally, it adds a few more C<Apache2::Const>. See L</CONSTANTS> below.

=head1 METHODS

=head2 init

Creates an instance of L<Apache2::API::Status> and returns the object.

=head2 convert_short_lang_to_long

Given a 2 characters language code (not case sensitive) and this will return its iso 639 5 characters equivalent for supported languages.

For example:

    Apache2::API::Status->convert_short_lang_to_long( 'zh' );
    # returns: zh_TW

=head2 is_cacheable_by_default

Return true if the 3-digits code provided indicates that a response is cacheable by default, and it can be reused by a cache with heuristic expiration. All other status codes are not cacheable by default. See L<RFC 7231 - HTTP/1.1 Semantics and Conte...

=head2 is_client_error

Returns true if the 3-digits code provided is between 400 and 500

=head2 is_error

Returns true if the 3-digits code provided is between 400 and 600

=head2 is_info

Returns true if the 3-digits code provided is between 100 and 200

=head2 is_redirect

Returns true if the 3-digits code provided is between 300 and 400

=head2 is_server_error

Returns true if the 3-digits code provided is between 500 and 600

=head2 is_success

Returns true if the 3-digits code provided is between 200 and 300

=head2 status_message

Provided with a 3-digits HTTP code and an optional language code such as C<en_GB> and this will return the status message in its localised form.

This is useful to provide response to error in the user preferred language. L<Apache2::API/reply> uses it to set a json response with the HTTP error code along with a localised status message.

If no language code is provided, this will default to C<en_GB>.

See L</supported_languages> for the supported languages.

=head2 status_to_type

Provided with a status code, such as C<404>, and this returns a status type such as C<not_found>.

This is used to build a rfc9457 compliant error.

=head2 supported_languages

This will return a sorted array reference of support languages for status codes.

The following language codes are currently supported: de_DE (German), en_GB (British English), fr_FR (French), ja_JP (Japanese), ko_KR (Korean), ru_RU (Russian) and zh_TW (Traditional Chinese as spoken in Taiwan).

Feel free to contribute those codes in other languages.

=head1 CONSTANTS

The following constants can be exported. You can use the C<:all> tag to export them all, such as:

    use Apache2::API::Status qw( :all );

or you can use the tag C<:common> to export the following common status codes:

    HTTP_NETWORK_AUTHENTICATION_REQUIRED
    HTTP_FORBIDDEN
    HTTP_NOT_FOUND
    HTTP_OK
    HTTP_TEMPORARY_REDIRECT
    HTTP_INTERNAL_SERVER_ERROR

=head2 HTTP_CONTINUE (100)

See L<rfc 7231, section 5.1.1|https://tools.ietf.org/html/rfc7231#section-5.1.1> and section L<6.2.1|https://tools.ietf.org/html/rfc7231#section-6.2.1> and L<Mozilla docs|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100>

This is provisional response returned by the web server upon an abbreviated request to find out whether the web server will accept the actual request. For example when the client is sending a large file in chunks, such as in C<PUT> request (here a 74...

    PUT /some//big/file.mp4 HTTP/1.1
    Host: www.example.org
    Content-Type: video/mp4
    Content-Length: 778043392
    Expect: 100-continue

If the server refused, it could return a C<413 Request Entity Too Large> or C<405 Method Not Allowed> or even C<401 Unauthorized>, or even a C<417 Expectation Failed> if it does not support this feature.

A response C<417 Expectation Failed> means the server is likely a HTTP/1.0 server or does not understand the request and the actual request must be sent, i.e. without the header field C<Expect: 100-continue>

In some REST API implementation, the server response code C<417> is used to mean the server understood the requested, but rejected it. This is a divergent use of the original purpose of this code.

=head2 HTTP_SWITCHING_PROTOCOLS (101)

See L<rfc7231, section 6.2.2|https://tools.ietf.org/html/rfc7231#section-6.2.2>

This is used to indicate that the TCP conncection is switching to a different protocol.

This is typically used for the L<WebSocket> protocol, which uses initially a HTTP handshake when establishing the connection. For example:

    GET /chat HTTP/1.1
    Host: server.example.com
    Upgrade: websocket
    Connection: Upgrade
    Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
    Origin: http://example.com
    Sec-WebSocket-Protocol: chat, superchat
    Sec-WebSocket-Version: 13