anil.recoil.org / ocaml-fastcgi
FastCGI implementation in OCaml
fork atom
ocaml-fastcgi / test / test_cases / README.md
at main 4.6 kB view raw view code

FastCGI Test Cases#

This directory contains binary test case files representing various FastCGI records as defined in the FastCGI specification. These files can be used to test a FastCGI parser implementation.

Test Case Files#

Management Records (requestId = 0)#

  • get_values.bin - FCGI_GET_VALUES record requesting capability information
  • get_values_result.bin - FCGI_GET_VALUES_RESULT record with capability responses
  • unknown_type.bin - FCGI_UNKNOWN_TYPE record for unrecognized record types

Application Records (requestId > 0)#

BEGIN_REQUEST Records#

  • begin_request_responder.bin - Begin request for Responder role with KEEP_CONN flag
  • begin_request_no_keep.bin - Begin request for Responder role without KEEP_CONN flag
  • begin_request_authorizer.bin - Begin request for Authorizer role
  • begin_request_filter.bin - Begin request for Filter role

Stream Records#

  • params_get.bin - FCGI_PARAMS record with GET request environment variables
  • params_post.bin - FCGI_PARAMS record with POST request environment variables
  • params_empty.bin - Empty FCGI_PARAMS record (end of params stream)
  • stdin_form_data.bin - FCGI_STDIN record with form data
  • stdin_empty.bin - Empty FCGI_STDIN record (end of stdin stream)
  • stdout_response.bin - FCGI_STDOUT record with HTTP response
  • stdout_empty.bin - Empty FCGI_STDOUT record (end of stdout stream)
  • stderr_message.bin - FCGI_STDERR record with error message
  • stderr_empty.bin - Empty FCGI_STDERR record (end of stderr stream)
  • data_filter.bin - FCGI_DATA record with file content (for Filter role)
  • data_empty.bin - Empty FCGI_DATA record (end of data stream)

Control Records#

  • end_request_success.bin - FCGI_END_REQUEST record with successful completion
  • end_request_error.bin - FCGI_END_REQUEST record with error status
  • abort_request.bin - FCGI_ABORT_REQUEST record

Complex Scenarios#

  • multiplexed_requests.bin - Multiple concurrent requests on same connection
  • large_record.bin - Record with maximum content size (65KB)
  • padded_record.bin - Record with padding for 8-byte alignment

Record Format#

All records follow the FastCGI record format:

typedef struct {
    unsigned char version;           // FCGI_VERSION_1 (1)
    unsigned char type;              // Record type (1-11)
    unsigned char requestIdB1;       // Request ID high byte
    unsigned char requestIdB0;       // Request ID low byte
    unsigned char contentLengthB1;   // Content length high byte
    unsigned char contentLengthB0;   // Content length low byte
    unsigned char paddingLength;     // Padding length
    unsigned char reserved;          // Reserved (always 0)
    // contentData[contentLength]
    // paddingData[paddingLength]
} FCGI_Record;

Usage for Parser Testing#

These test cases can be used to verify:

  1. Header parsing - Correct extraction of version, type, requestId, lengths
  2. Content parsing - Proper handling of record body data
  3. Stream handling - Recognition of stream start/end patterns
  4. Name-value pair parsing - Decoding of FCGI_PARAMS format
  5. Role-specific parsing - Different record sequences for each role
  6. Error handling - Response to unknown types, malformed data
  7. Multiplexing - Handling multiple concurrent request IDs
  8. Padding - Correct skipping of padding bytes

Typical Protocol Flows#

Simple Responder Request#

  1. begin_request_responder.bin
  2. params_get.bin
  3. params_empty.bin
  4. stdin_empty.bin
  5. stdout_response.bin
  6. stdout_empty.bin
  7. end_request_success.bin

POST Request with Form Data#

  1. begin_request_responder.bin
  2. params_post.bin
  3. params_empty.bin
  4. stdin_form_data.bin
  5. stdin_empty.bin
  6. stdout_response.bin
  7. stdout_empty.bin
  8. end_request_success.bin

Authorizer Request#

  1. begin_request_authorizer.bin
  2. params_get.bin
  3. params_empty.bin
  4. stdout_response.bin
  5. stdout_empty.bin
  6. end_request_success.bin

Filter Request#

  1. begin_request_filter.bin
  2. params_get.bin
  3. params_empty.bin
  4. stdin_empty.bin
  5. data_filter.bin
  6. data_empty.bin
  7. stdout_response.bin
  8. stdout_empty.bin
  9. end_request_success.bin

Binary Format Verification#

You can inspect the binary content using hexdump:

hexdump -C begin_request_responder.bin

The first 8 bytes should always be the FastCGI header, followed by the record content and any padding.