Net::FastCGI::Protocol - Provides functions to build and parse FastCGI messages.
# FCGI_Header $octets = build_header($type, $request_id, $content_length, $padding_length); @values = parse_header($octets); $header = parse_header($octets); # FCGI_BeginRequestBody $octets = build_begin_request_body($role, $flags); @values = parse_begin_request_body($octets); # FCGI_EndRequestBody $octets = build_end_request_body($app_status, $protocol_status); @values = parse_end_request_body($octets); # FCGI_UnknownTypeBody $octets = build_unknown_type_body($type); @values = parse_unknown_type_body($octets); # FCGI_BeginRequestRecord $octets = build_begin_request_record($request_id, $role, $flags); # FCGI_EndRequestRecord $octets = build_end_request_record($request_id, $app_status, $protocol_status); # FCGI_UnknownTypeRecord $octets = build_unknown_type_record($type); # FCGI_NameValuePair's $octets = build_params($params); $params = parse_params($octets); $bool = check_params($octets); # FCGI_Record $octets = build_record($type, $request_id); $octets = build_record($type, $request_id, $content); @values = parse_record($octets); $record = parse_record($octets); $record = parse_record_body($type, $request_id, $content); # FCGI_Record Debugging / Tracing $string = dump_record($octets); $string = dump_record_body($type, $request_id, $content); # FCGI_Record Stream $octets = build_stream($type, $request_id, $content); $octets = build_stream($type, $request_id, $content, $terminate); # Begin Request $octets = build_begin_request($request_id, $role, $flags, $params); $octets = build_begin_request($request_id, $role, $flags, $params, $stdin); $octets = build_begin_request($request_id, $role, $flags, $params, $stdin, $data); # End Request $octets = build_end_request($request_id, $app_status, $protocol_status); $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout); $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout, $stderr);
Provides functions to build and parse FastCGI messages.
Please note that all functions in this package expects octets, not unicode strings. It's the callers responsibility to ensure this. If any of theese functions is called with unicode strings containing code points above 255, they will most likely produce malformed messages.
Builds a Begin Request message.
Usage
$octets = build_begin_request($request_id, $role, $flags, $params); $octets = build_begin_request($request_id, $role, $flags, $params, $stdin); $octets = build_begin_request($request_id, $role, $flags, $params, $stdin, $data);
Arguments
$request_id
An unsigned 16-bit integer. Identifier of the request.
$role
An unsigned 16-bit integer. This should be set to either FCGI_RESPONDER, FCGI_AUTHORIZER or FCGI_FILTER.
FCGI_RESPONDER
FCGI_AUTHORIZER
FCGI_FILTER
$flags
An unsigned 8-bit integer. This should be set to either 0 or contain the mask FCGI_KEEP_CONN if a persistent connection is desired.
0
FCGI_KEEP_CONN
$params
A hash reference containing name-value pairs. This is the CGI environ that the application expects.
$stdin
A string of octets containing the FCGI_STDIN content. This should only be provided if $role is set to either FCGI_RESPONDER or FCGI_FILTER. The FCGI_STDIN stream is terminated if provided.
FCGI_STDIN
$data
A string of octets containing the FCGI_DATA content. This should only be provided if $role is set to FCGI_FILTER. The FCGI_DATA stream is terminated if provided.
FCGI_DATA
Returns
$octets
A string of octets containing the message.
Builds a FCGI_BeginRequestBody.
FCGI_BeginRequestBody
$octets = build_begin_request_body($role, $flags);
An unsigned 16-bit integer.
An unsigned 8-bit integer.
A string of octets containing the body. String is 8 octets in length.
Builds a FCGI_BeginRequestRecord.
FCGI_BeginRequestRecord
$octets = build_begin_request_record($request_id, $role, $flags);
A string of octets containing the record. String is 16 octets in length.
Builds a End Request message
$octets = build_end_request($request_id, $app_status, $protocol_status); $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout); $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout, $stderr);
$app_status
An unsigned 32-bit integer. Application status code of the request.
$protocol_status
An unsigned 8-bit integer. This should be set to either FCGI_REQUEST_COMPLETE, FCGI_CANT_MPX_CONN, FCGI_OVERLOADED or FCGI_UNKNOWN_ROLE.
FCGI_REQUEST_COMPLETE
FCGI_CANT_MPX_CONN
FCGI_OVERLOADED
FCGI_UNKNOWN_ROLE
$stdout
A string of octets containing the FCGI_STDOUT content. The FCGI_STDOUT stream is terminated if provided.
FCGI_STDOUT
$stderr
A string of octets containing the FCGI_STDERR content. The FCGI_STDERR stream is terminated if provided.
FCGI_STDERR
Note
This function is equivalent to build_end_request_record() if called without $stdout and $stderr.
build_end_request_record()
Builds a FCGI_EndRequestBody.
FCGI_EndRequestBody
$octets = build_end_request_body($app_status, $protocol_status);
An unsigned 32-bit integer.
Builds a FCGI_EndRequestRecord.
FCGI_EndRequestRecord
$octets = build_end_request_record($request_id, $app_status, $protocol_status);
Builds a FCGI_Header.
FCGI_Header
$octets = build_header($type, $request_id, $content_length, $padding_length);
$type
$content_length
$padding_length
A string of octets containing the header. String is 8 octets in length.
Builds FCGI_NameValuePair's.
FCGI_NameValuePair
$octets = build_params($params);
A hash reference containing name-value pairs.
Builds a FCGI_Record.
FCGI_Record
$octets = build_record($type, $request_id); $octets = build_record($type, $request_id, $content);
$content
A string of octets containing the content, cannot exceed 65535 octets in length.
A string of octets containing the record.
Follows the recommendation in specification and pads the record by 8-(content_length mod 8) zero-octets.
Builds a series of stream records.
$octets = build_stream($type, $request_id, $content); $octets = build_stream($type, $request_id, $content, $terminate);
A string of octets containing the stream content.
$terminate
A boolean indicating whether or not the stream should be terminated. Defaults to false.
A string of octets containing the stream.
Stream is not terminated if $content is empty unless $terminate is set.
$content is split in segment sizes of 32760 octets (32768 - FCGI_HEADER_LEN).
Builds a FCGI_UnknownTypeBody.
FCGI_UnknownTypeBody
$octets = build_unknown_type_body($type);
Builds a FCGI_UnknownTypRecord.
FCGI_UnknownTypRecord
$octets = build_unknown_type_record($type);
Determine wheter or not params is well-formed.
$boolean = check_params($octets);
A string of octets containing FCGI_NameValuePair's.
$boolean
A boolean indicating whether or not $octets consist of well-formed FCGI_NameValuePair's.
Dump a FCGI_Record.
$string = dump_record($octets);
A string of octets containing at least one record.
$string
A short (less than 100 characters) string representation of the record in printable US-ASCII.
$string = dump_record_body($type, $request_id); $string = dump_record_body($type, $request_id, $content);
A string of octets containing the content.
Parses a FCGI_BeginRequestBody.
($role, $flags) = parse_begin_request_body($octets);
A string of octets containing the body, must be greater than or equal to 8 octets in length.
Parses a FCGI_EndRequestBody.
($app_status, $protocol_status) = parse_end_request_body($octets);
Parses a FCGI_Header.
($type, $request_id, $content_length, $padding_length) = parse_header($octets); $header = parse_header($octets); say $header->{type}; say $header->{request_id}; say $header->{content_length}; say $header->{padding_length};
A string of octets containing the header, must be greater than or equal to 8 octets in length.
In list context:
In scalar context a hash reference containing above variable names as keys.
Parses FCGI_NameValuePair's.
$params = parse_params($octets);
Parses a FCGI_Record.
($type, $request_id, $content) = parse_record($octets); $record = parse_record($octets); say $record->{type}; say $record->{request_id};
A string of octets containing the record content.
In scalar context a hash reference containing the FCGI_Record components. See "parse_record_body".
$record = parse_record_body($type, $request_id, $content); say $record->{type}; say $record->{request_id};
A hash reference which represents the FCGI_Record. The content depends on the type of record. All record types have the keys: type and request_id.
type
request_id
FCGI_BEGIN_REQUEST
role
flags
FCGI_END_REQUEST
app_status
protocol_status
FCGI_PARAMS
content
A string of octets containing the content of the stream.
FCGI_GET_VALUES
FCGI_GET_VALUES_RESULT
values
FCGI_UNKNOWN_TYPE
unknown_type
Parses a FCGI_UnknownTypeBody.
$type = parse_unknown_type_body($octets);
$octets must be greater than or equal to 8 octets in length.
$length = get_record_length($octets);
A string of octets containing at least one FCGI_Header.
$length
An unsigned integer containing the length of record in octets. If $octets contains insufficient octets (< FCGI_HEADER_LEN) 0 is returned.
(< FCGI_HEADER_LEN)
$name = get_type_name($type); $name = get_type_name(FCGI_BEGIN_REQUEST); # 'FCGI_BEGIN_REQUEST' $name = get_type_name(255); # '0xFF'
$name
A string containing the name of the type. If $type is not a known v1.0 type, a hexadecimal value is returned.
See also ":name" in Net::FastCGI::Constant.
$name = get_role_name($type); $name = get_role_name(FCGI_RESPONDER); # 'FCGI_RESPONDER' $name = get_role_name(65535); # '0xFFFF'
A string containing the name of the role. If $role is not a known v1.0 role, a hexadecimal value is returned.
$name = get_protocol_status_name($protocol_status); $name = get_protocol_status_name(FCGI_REQUEST_COMPLETE); # 'FCGI_REQUEST_COMPLETE' $name = get_protocol_status_name(255); # '0xFF'
A string containing the name of the protocol status. If $protocol_status is not a known v1.0 protocol status code, a hexadecimal value is returned.
$boolean = is_known_type($type);
A boolean indicating whether or not $type is a known FastCGI v1.0 type.
$boolean = is_management_type($type);
A boolean indicating whether or not $type is a management type.
$boolean = is_discrete_type($type);
A boolean indicating whether or not $type is a discrete type.
$boolean = is_stream_type($type);
A boolean indicating whether or not $type is a stream type.
None by default. All functions can be exported using the :all tag or individually.
:all
Subroutine called with wrong number of arguments.
http://www.fastcgi.com/devkit/doc/fcgi-spec.html
http://tools.ietf.org/html/rfc3875
Christian Hansen chansen@cpan.org
chansen@cpan.org
Copyright 2008-2010 by Christian Hansen.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Net::FastCGI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::FastCGI
CPAN shell
perl -MCPAN -e shell install Net::FastCGI
For more information on module installation, please visit the detailed CPAN module installation guide.