FastCGI implementation in OCaml
anil.recoil.org
1# FastCGI Test Cases
2
3This 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.
4
5## Test Case Files
6
7### Management Records (requestId = 0)
8
9- **`get_values.bin`** - FCGI_GET_VALUES record requesting capability information
10- **`get_values_result.bin`** - FCGI_GET_VALUES_RESULT record with capability responses
11- **`unknown_type.bin`** - FCGI_UNKNOWN_TYPE record for unrecognized record types
12
13### Application Records (requestId > 0)
14
15#### BEGIN_REQUEST Records
16- **`begin_request_responder.bin`** - Begin request for Responder role with KEEP_CONN flag
17- **`begin_request_no_keep.bin`** - Begin request for Responder role without KEEP_CONN flag
18- **`begin_request_authorizer.bin`** - Begin request for Authorizer role
19- **`begin_request_filter.bin`** - Begin request for Filter role
20
21#### Stream Records
22- **`params_get.bin`** - FCGI_PARAMS record with GET request environment variables
23- **`params_post.bin`** - FCGI_PARAMS record with POST request environment variables
24- **`params_empty.bin`** - Empty FCGI_PARAMS record (end of params stream)
25- **`stdin_form_data.bin`** - FCGI_STDIN record with form data
26- **`stdin_empty.bin`** - Empty FCGI_STDIN record (end of stdin stream)
27- **`stdout_response.bin`** - FCGI_STDOUT record with HTTP response
28- **`stdout_empty.bin`** - Empty FCGI_STDOUT record (end of stdout stream)
29- **`stderr_message.bin`** - FCGI_STDERR record with error message
30- **`stderr_empty.bin`** - Empty FCGI_STDERR record (end of stderr stream)
31- **`data_filter.bin`** - FCGI_DATA record with file content (for Filter role)
32- **`data_empty.bin`** - Empty FCGI_DATA record (end of data stream)
33
34#### Control Records
35- **`end_request_success.bin`** - FCGI_END_REQUEST record with successful completion
36- **`end_request_error.bin`** - FCGI_END_REQUEST record with error status
37- **`abort_request.bin`** - FCGI_ABORT_REQUEST record
38
39### Complex Scenarios
40- **`multiplexed_requests.bin`** - Multiple concurrent requests on same connection
41- **`large_record.bin`** - Record with maximum content size (65KB)
42- **`padded_record.bin`** - Record with padding for 8-byte alignment
43
44## Record Format
45
46All records follow the FastCGI record format:
47
48```
49typedef struct {
50 unsigned char version; // FCGI_VERSION_1 (1)
51 unsigned char type; // Record type (1-11)
52 unsigned char requestIdB1; // Request ID high byte
53 unsigned char requestIdB0; // Request ID low byte
54 unsigned char contentLengthB1; // Content length high byte
55 unsigned char contentLengthB0; // Content length low byte
56 unsigned char paddingLength; // Padding length
57 unsigned char reserved; // Reserved (always 0)
58 // contentData[contentLength]
59 // paddingData[paddingLength]
60} FCGI_Record;
61```
62
63## Usage for Parser Testing
64
65These test cases can be used to verify:
66
671. **Header parsing** - Correct extraction of version, type, requestId, lengths
682. **Content parsing** - Proper handling of record body data
693. **Stream handling** - Recognition of stream start/end patterns
704. **Name-value pair parsing** - Decoding of FCGI_PARAMS format
715. **Role-specific parsing** - Different record sequences for each role
726. **Error handling** - Response to unknown types, malformed data
737. **Multiplexing** - Handling multiple concurrent request IDs
748. **Padding** - Correct skipping of padding bytes
75
76## Typical Protocol Flows
77
78### Simple Responder Request
791. `begin_request_responder.bin`
802. `params_get.bin`
813. `params_empty.bin`
824. `stdin_empty.bin`
835. `stdout_response.bin`
846. `stdout_empty.bin`
857. `end_request_success.bin`
86
87### POST Request with Form Data
881. `begin_request_responder.bin`
892. `params_post.bin`
903. `params_empty.bin`
914. `stdin_form_data.bin`
925. `stdin_empty.bin`
936. `stdout_response.bin`
947. `stdout_empty.bin`
958. `end_request_success.bin`
96
97### Authorizer Request
981. `begin_request_authorizer.bin`
992. `params_get.bin`
1003. `params_empty.bin`
1014. `stdout_response.bin`
1025. `stdout_empty.bin`
1036. `end_request_success.bin`
104
105### Filter Request
1061. `begin_request_filter.bin`
1072. `params_get.bin`
1083. `params_empty.bin`
1094. `stdin_empty.bin`
1105. `data_filter.bin`
1116. `data_empty.bin`
1127. `stdout_response.bin`
1138. `stdout_empty.bin`
1149. `end_request_success.bin`
115
116## Binary Format Verification
117
118You can inspect the binary content using hexdump:
119```bash
120hexdump -C begin_request_responder.bin
121```
122
123The first 8 bytes should always be the FastCGI header, followed by the record content and any padding.