Christian Hansen

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);
    
    # FCGI_Record
    $octets = build_record($type, $request_id);
    $octets = build_record($type, $request_id, $content);
    $record = parse_record($octets);
    $record = parse_record_body($type, $request_id, $content);
    
    # Stream
    $octets = build_stream($type, $request_id, $octets);
    $octets = build_stream($type, $request_id, $octets, $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

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. ID 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. Typically this is the CGI environ that the application expects.

$stdin (optional)

A string of octets containing the FCGI_STDIN data. This should only be provided if $role is set to either FCGI_RESPONDER or FCGI_FILTER. Maybe undef or empty. Stream is terminated if provided.

$data (optional)

A string of octets containing the FCGI_DATA data. This should only be provided if $role is set to FCGI_FILTER. Maybe undef or empty. 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. ID 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 data. Maybe undef or empty. Stream is terminated if provided.

$stderr (optional)

A string of octets containing the FCGI_STDERR data. Maybe undef or empty. 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. May be undef.

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. May be undef.

$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 undef or 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.

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);
    print $header->{type};
    print $header->{request_id};

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

    $record = parse_record($octets);

Arguments

$octets

A string of octets containing at least one record.

Returns

A hash reference which represents the record. The content depends on the type of record. All record types have the keys: type and request_id.

FCGI_BEGIN_REQUEST
role
flags
FCGI_END_REQUEST
app_status
protocol_status
FCGI_PARAMS
FCGI_STDIN
FCGI_DATA
FCGI_STDOUT
FCGI_STDERR
content

A string of octets containing the content of the stream. Can be empty but not undef.

FCGI_GET_VALUES
FCGI_GET_VALUES_RESULT
values

A hash reference containing name-value pairs.

FCGI_UNKNOWN_TYPE
unknown_type

parse_record_body

Parses a FCGI_Record body.

Usage

    $record = parse_record_body($type, $request_id, $content);

Arguments

$type

An unsigned 8-bit integer.

$request_id

An unsigned 16-bit integer.

$content

A string of octets containing the record content.

Returns

Returns a hash reference containing the FCGI_Record components. See "parse_record".

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_type_name

Usage

    $name = get_type_name($type);

Arguments

$type

An unsigned 8-bit integer.

Returns

$name

A string containing the name of the type.

get_role_name

Usage

    $name = get_role_name($type);

Arguments

$role

An unsigned 16-bit integer.

Returns

$name

A string containing the name of the role.

get_protocol_status_name

Usage

    $name = get_protocol_status_name($protocol_status);

Arguments

$protocol_status

An unsigned 8-bit integer.

Returns

$name

A string containing the name of the protocol status.

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

SEE ALSO

FastCGI Specification Version 1.0

http://www.fastcgi.com/devkit/doc/fcgi-spec.html

The Common Gateway Interface (CGI) Version 1.1

http://tools.ietf.org/html/rfc3875

Net::FastCGI::Constant

AUTHOR

Christian Hansen chansen@cpan.org

COPYRIGHT

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.