File: README

package info (click to toggle)
libhttp-parser-xs-perl 0.17-2
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, forky, sid, trixie
  • size: 452 kB
  • sloc: perl: 1,881; ansic: 926; makefile: 13
file content (173 lines) | stat: -rw-r--r-- 5,821 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
NAME
    HTTP::Parser::XS - a fast, primitive HTTP request parser

SYNOPSIS
      use HTTP::Parser::XS qw(parse_http_request);

      # for HTTP servers
      my $ret = parse_http_request(
          "GET / HTTP/1.0\r\nHost: ...\r\n\r\n",
          \%env,
      );
      if ($ret == -2) {
          # request is incomplete
          ...
      } elsif ($ret == -1) {
          # request is broken
          ...
      } else {
          # $ret includes the size of the request, %env now contains a PSGI
          # request, if it is a POST / PUT request, read request content by
          # yourself
          ...
      }


      # for HTTP clients
      use HTTP::Parser::XS qw(parse_http_response HEADERS_AS_ARRAYREF);
      my %special_headers = (
        'content-length' => undef,
      );
      my($ret, $minor_version, $status, $message, $headers)
        = parse_http_response($response, HEADERS_AS_ARRAYREF, \%special_headers);

      if($ret == -1) }
        # response is incomplete
      }
      elsif($ret == -2) {
        # response is broken
      }
      else {
        # $ret is the length of the headers, starting the content body

        # the other values are the response messages. For example:
        # $status  = 200
        # $message = "OK"
        # $headers = [ 'content-type' => 'text/html', ... ]

        # and $special_headers{'content-length'} will be filled in
      }

DESCRIPTION
    HTTP::Parser::XS is a fast, primitive HTTP request/response parser.

    The request parser can be used either for writing a synchronous HTTP
    server or a event-driven server.

    The response parser can be used for writing HTTP clients.

    Note that even if this distribution name ends "::XS", pure Perl
    implementation is supported, so you can use this module on compiler-less
    environments.

FUNCTIONS
    parse_http_request($request_string, \%env)
        Tries to parse given request string, and if successful, inserts
        variables into %env. For the name of the variables inserted, please
        refer to the PSGI specification. The return values are:

        >=0     length of the request (request line and the request
                headers), in bytes

        -1      given request is corrupt

        -2      given request is incomplete

        Note that the semantics of PATH_INFO is somewhat different from
        Apache. First, HTTP::Parser::XS does not validate the variable; it
        does not raise an error even if PATH_INFO does not start with "/".
        Second, the variable is conformant to RFC 3875 (and PSGI / Plack) in
        the fact that "//" and ".." appearing in PATH_INFO are preserved
        whereas Apache transcodes them.

    parse_http_response($response_string, $header_format, \%special_headers)
        Tries to parse given response string. *$header_format* must be
        "HEADERS_AS_ARRAYREF", "HEADERS_AS_HASHREF", or "HEADERS_NONE",
        which are exportable constants.

        The optional *%special_headers* is for headers you specifically
        require. You can set any HTTP response header names, which must be
        lower-cased, and their default values, and then the values are
        filled in by "parse_http_response()". For example, if you want the
        "Cointent-Length" field, set its name with default values like "%h =
        ('content-length' => undef)" and pass it as *%special_headers*.
        After parsing, $h{'content-length'} is set if the response has the
        "Content-Length" field, otherwise it's not touched.

        The return values are:

        $ret    The parsering status, which is the same as
                "parse_http_response()". i.e. the length of the response
                headers in bytes, -1 for incomplete headers, or -2 for
                errors.

                If the given response string is broken or imcomplete,
                "parse_http_response()" returns only this value.

        $minor_version
                The minor version of the given response. i.e. 1 for
                HTTP/1.1, 0 for HTTP/1.0.

        $status The HTTP status of the given response. e.g. 200 for success.

        $message
                The HTTP status message. e.g. "OK" for success.

        $headers
                The HTTP headers for the given response. It is an ARRAY
                reference if *$header_format* is "HEADERS_AS_ARRAYREF", a
                HASH reference on "HEADERS_AS_HASHREF", an "undef" on
                "HEADERS_NONE".

                The names of the headers are normalized to lower-cased.

LIMITATIONS
    Both "parse_http_request()" and "parse_http_response()" in XS
    implementation have some size limitations.

  The number of headers
    The number of headers is limited to 128. If it exceeds, both parsing
    routines report parsing errors, i.e. return -1 for $ret.

  The size of header names
    The size of header names is limited to 1024, but the parsers do not the
    same action.

    "parse_http_request()" returns -1 if too-long header names exist.

    "parse_http_request()" simply ignores too-long header names.

COPYRIGHT
    Copyright 2009- Kazuho Oku

AUTHORS
    *   Kazuho Oku <https://metacpan.org/author/KAZUHO>

    *   gfx <https://metacpan.org/author/GFUJI>

    *   mala <https://metacpan.org/author/MALA>

    *   tokuhirom <https://metacpan.org/author/TOKUHIROM>

THANKS TO
    *   nothingmuch <https://metacpan.org/author/NUFFIN>

    *   charsbar <https://metacpan.org/author/CHARSBAR>

    *   DOLMEN <https://metacpan.org/author/DOLMEN>

SEE ALSO
    *   <http://github.com/kazuho/picohttpparser>

    *   HTTP::Parser

    *   HTTP::HeaderParser::XS

    *   Plack

    *   PSGI

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