Index

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS
EXPORTS
DIAGNOSTICS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

Net::FastCGI::Protocol - Provides functions to build and parse FastCGI messages.

SYNOPSIS

    # 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);

DESCRIPTION

Provides functions to build and parse FastCGI messages.

FUNCTIONS

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.

build_begin_request

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.
$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.
$params: A hash reference containing name-value pairs. This is the CGI environ that the application expects.
$stdin (optional): 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.
$data (optional): 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.

Returns

$octets: A string of octets containing the message.

build_begin_request_body

Builds a FCGI_BeginRequestBody.

Usage

    $octets = build_begin_request_body($role, $flags);

Arguments

$role: An unsigned 16-bit integer.
$flags: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the body. String is 8 octets in length.

build_begin_request_record

Builds a FCGI_BeginRequestRecord.

Usage

    $octets = build_begin_request_record($request_id, $role, $flags);

Arguments

$request_id: An unsigned 16-bit integer.
$role: An unsigned 16-bit integer.
$flags: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the record. String is 16 octets in length.

build_end_request

Builds a End Request message

Usage

    $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);

Arguments

$request_id: An unsigned 16-bit integer. Identifier of the request.
$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.
$stdout (optional): A string of octets containing the FCGI_STDOUT content. The FCGI_STDOUT stream is terminated if provided.
$stderr (optional): A string of octets containing the FCGI_STDERR content. The FCGI_STDERR stream is terminated if provided.

Returns

$octets: A string of octets containing the message.

Note

This function is equivalent to build_end_request_record() if called without $stdout and $stderr.

build_end_request_body

Builds a FCGI_EndRequestBody.

Usage

    $octets = build_end_request_body($app_status, $protocol_status);

Arguments

$app_status: An unsigned 32-bit integer.
$protocol_status: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the body. String is 8 octets in length.

build_end_request_record

Builds a FCGI_EndRequestRecord.

Usage

    $octets = build_end_request_record($request_id, $app_status, $protocol_status);

Arguments

$request_id: An unsigned 16-bit integer.
$app_status: An unsigned 32-bit integer.
$protocol_status: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the record. String is 16 octets in length.

build_header

Builds a FCGI_Header.

Usage

    $octets = build_header($type, $request_id, $content_length, $padding_length);

Arguments

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content_length: An unsigned 16-bit integer.
$padding_length: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the header. String is 8 octets in length.

build_params

Builds FCGI_NameValuePair's.

Usage

    $octets = build_params($params);

Arguments

$params: A hash reference containing name-value pairs.

Returns

$octets

build_record

Builds a FCGI_Record.

Usage

    $octets = build_record($type, $request_id);
    $octets = build_record($type, $request_id, $content);

Arguments

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content (optional): A string of octets containing the content, cannot exceed 65535 octets in length.

Returns

$octets: A string of octets containing the record.

Note

Follows the recommendation in specification and pads the record by 8-(content_length mod 8) zero-octets.

build_stream

Builds a series of stream records.

Usage

    $octets = build_stream($type, $request_id, $content);
    $octets = build_stream($type, $request_id, $content, $terminate);

Arguments

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content: A string of octets containing the stream content.
$terminate (optional): A boolean indicating whether or not the stream should be terminated. Defaults to false.

Returns

$octets: A string of octets containing the stream.

Note

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).

build_unknown_type_body

Builds a FCGI_UnknownTypeBody.

Usage

    $octets = build_unknown_type_body($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the body. String is 8 octets in length.

build_unknown_type_record

Builds a FCGI_UnknownTypRecord.

Usage

    $octets = build_unknown_type_record($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$octets: A string of octets containing the record. String is 16 octets in length.

check_params

Determine wheter or not params is well-formed.

Usage

    $boolean = check_params($octets);

Arguments

$octets: A string of octets containing FCGI_NameValuePair's.

Returns

$boolean: A boolean indicating whether or not $octets consist of well-formed FCGI_NameValuePair's.

dump_record

Dump a FCGI_Record.

Usage

    $string = dump_record($octets);

Arguments

$octets: A string of octets containing at least one record.

Returns

$string: A short (less than 100 characters) string representation of the record in printable US-ASCII.

dump_record_body

Dump a FCGI_Record.

Usage

    $string = dump_record_body($type, $request_id);
    $string = dump_record_body($type, $request_id, $content);

Arguments

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content (optional): A string of octets containing the content.

Returns

$string: A short (less than 100 characters) string representation of the record in printable US-ASCII.

parse_begin_request_body

Parses a FCGI_BeginRequestBody.

Usage

    ($role, $flags) = parse_begin_request_body($octets);

Arguments

$octets: A string of octets containing the body, must be greater than or equal to 8 octets in length.

Returns

$role: An unsigned 16-bit integer.
$flags: An unsigned 8-bit integer.

parse_end_request_body

Parses a FCGI_EndRequestBody.

Usage

    ($app_status, $protocol_status) = parse_end_request_body($octets);

Arguments

$octets: A string of octets containing the body, must be greater than or equal to 8 octets in length.

Returns

$app_status: An unsigned 32-bit integer.
$flags: An unsigned 8-bit integer.

parse_header

Parses a FCGI_Header.

Usage

    ($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};

Arguments

$octets: A string of octets containing the header, must be greater than or equal to 8 octets in length.

Returns

In list context:

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content_length: An unsigned 16-bit integer.
$padding_length: An unsigned 8-bit integer.

In scalar context a hash reference containing above variable names as keys.

parse_params

Parses FCGI_NameValuePair's.

Usage

    $params = parse_params($octets);

Arguments

$octets: A string of octets containing FCGI_NameValuePair's.

Returns

$params: A hash reference containing name-value pairs.

parse_record

Parses a FCGI_Record.

Usage

    ($type, $request_id, $content)
      = parse_record($octets);

    $record = parse_record($octets);
    say $record->{type};
    say $record->{request_id};

Arguments

$octets: A string of octets containing at least one record.

Returns

In list context:

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content: A string of octets containing the record content.

In scalar context a hash reference containing the FCGI_Record components. See parse_record_body.

parse_record_body

Parses a FCGI_Record.

Usage

    $record = parse_record_body($type, $request_id, $content);
    say $record->{type};
    say $record->{request_id};

Arguments

$type: An unsigned 8-bit integer.
$request_id: An unsigned 16-bit integer.
$content: A string of octets containing the record content.

Returns

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.

FCGI_BEGIN_REQUEST
FCGI_END_REQUEST
FCGI_PARAMS
FCGI_STDIN
FCGI_DATA
FCGI_STDOUT
FCGI_STDERR
FCGI_GET_VALUES
FCGI_GET_VALUES_RESULT
FCGI_UNKNOWN_TYPE

parse_unknown_type_body

Parses a FCGI_UnknownTypeBody.

Usage

    $type = parse_unknown_type_body($octets);

Arguments

$octets: $octets must be greater than or equal to 8 octets in length.

Returns

$type: An unsigned 8-bit integer.

get_record_length

Usage

    $length = get_record_length($octets);

Arguments

$octets: A string of octets containing at least one FCGI_Header.

Returns

$length: An unsigned integer containing the length of record in octets. If $octets contains insufficient octets (< FCGI_HEADER_LEN) 0 is returned.

get_type_name

Usage

    $name = get_type_name($type);
    $name = get_type_name(FCGI_BEGIN_REQUEST);  # 'FCGI_BEGIN_REQUEST'
    $name = get_type_name(255);                 # '0xFF'

Arguments

$type: An unsigned 8-bit integer.

Returns

$name: A string containing the name of the type. If $type is not a known v1.0 type, a hexadecimal value is returned.

Note

get_role_name

Usage

    $name = get_role_name($type);
    $name = get_role_name(FCGI_RESPONDER);  # 'FCGI_RESPONDER'
    $name = get_role_name(65535);           # '0xFFFF'

Arguments

$role: An unsigned 16-bit integer.

Returns

$name: A string containing the name of the role. If $role is not a known v1.0 role, a hexadecimal value is returned.

Note

get_protocol_status_name

Usage

    $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'

Arguments

$protocol_status: An unsigned 8-bit integer.

Returns

$name: 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.

Note

is_known_type

Usage

    $boolean = is_known_type($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$boolean: A boolean indicating whether or not $type is a known FastCGI v1.0 type.

is_management_type

Usage

    $boolean = is_management_type($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$boolean: A boolean indicating whether or not $type is a management type.

is_discrete_type

Usage

    $boolean = is_discrete_type($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$boolean: A boolean indicating whether or not $type is a discrete type.

is_stream_type

Usage

    $boolean = is_stream_type($type);

Arguments

$type: An unsigned 8-bit integer.

Returns

$boolean: A boolean indicating whether or not $type is a stream type.

EXPORTS

None by default. All functions can be exported using the :all tag or individually.

DIAGNOSTICS

(F) Usage: %s: Subroutine called with wrong number of arguments.
(F) Invalid Argument: %s
(F) FastCGI: Insufficient number of octets to parse %s
(F) FastCGI: Malformed record %s
(F) FastCGI: Protocol version mismatch (0x%.2X)

AUTHOR

Christian Hansen chansen@cpan.org

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Net::FastCGI::Protocol - Provides functions to build and parse FastCGI messages.

Index

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

build_begin_request

build_begin_request_body

build_begin_request_record

build_end_request

build_end_request_body

build_end_request_record

build_header

build_params

build_record

build_stream

build_unknown_type_body

build_unknown_type_record

check_params

dump_record

dump_record_body

parse_begin_request_body

parse_end_request_body

parse_header

parse_params

parse_record

parse_record_body

parse_unknown_type_body

get_record_length

get_type_name

get_role_name

get_protocol_status_name

is_known_type

is_management_type

is_discrete_type

is_stream_type

EXPORTS

DIAGNOSTICS

SEE ALSO

AUTHOR

COPYRIGHT