git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/http-parser/http_parser.h

   1 /* Copyright Joyent, Inc. and other Node contributors. All rights reserved.\r
   2  *\r
   3  * Permission is hereby granted, free of charge, to any person obtaining a copy\r
   4  * of this software and associated documentation files (the "Software"), to\r
   5  * deal in the Software without restriction, including without limitation the\r
   6  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\r
   7  * sell copies of the Software, and to permit persons to whom the Software is\r
   8  * furnished to do so, subject to the following conditions:\r
   9  *\r
  10  * The above copyright notice and this permission notice shall be included in\r
  11  * all copies or substantial portions of the Software.\r
  12  *\r
  13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  14  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r
  15  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r
  16  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r
  17  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\r
  18  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\r
  19  * IN THE SOFTWARE.\r
  20  */\r
  21 #ifndef http_parser_h\r
  22 #define http_parser_h\r
  23 #ifdef __cplusplus\r
  24 extern "C" {\r
  25 #endif\r
  26 \r
  27 /* Also update SONAME in the Makefile whenever you change these. */\r
  28 #define HTTP_PARSER_VERSION_MAJOR 2\r
  29 #define HTTP_PARSER_VERSION_MINOR 9\r
  30 #define HTTP_PARSER_VERSION_PATCH 2\r
  31 \r
  32 #include <stddef.h>\r
  33 #if defined(_WIN32) && !defined(__MINGW32__) && \\r
  34   (!defined(_MSC_VER) || _MSC_VER<1600) && !defined(__WINE__)\r
  35 #include <BaseTsd.h>\r
  36 typedef __int8 int8_t;\r
  37 typedef unsigned __int8 uint8_t;\r
  38 typedef __int16 int16_t;\r
  39 typedef unsigned __int16 uint16_t;\r
  40 typedef __int32 int32_t;\r
  41 typedef unsigned __int32 uint32_t;\r
  42 typedef __int64 int64_t;\r
  43 typedef unsigned __int64 uint64_t;\r
  44 #else\r
  45 #include <stdint.h>\r
  46 #endif\r
  47 \r
  48 /* Compile with -DHTTP_PARSER_STRICT=0 to make less checks, but run\r
  49  * faster\r
  50  */\r
  51 #ifndef HTTP_PARSER_STRICT\r
  52 # define HTTP_PARSER_STRICT 1\r
  53 #endif\r
  54 \r
  55 /* Maximium header size allowed. If the macro is not defined\r
  56  * before including this header then the default is used. To\r
  57  * change the maximum header size, define the macro in the build\r
  58  * environment (e.g. -DHTTP_MAX_HEADER_SIZE=<value>). To remove\r
  59  * the effective limit on the size of the header, define the macro\r
  60  * to a very large number (e.g. -DHTTP_MAX_HEADER_SIZE=0x7fffffff)\r
  61  */\r
  62 #ifndef HTTP_MAX_HEADER_SIZE\r
  63 # define HTTP_MAX_HEADER_SIZE (80*1024)\r
  64 #endif\r
  65 \r
  66 typedef struct http_parser http_parser;\r
  67 typedef struct http_parser_settings http_parser_settings;\r
  68 \r
  69 \r
  70 /* Callbacks should return non-zero to indicate an error. The parser will\r
  71  * then halt execution.\r
  72  *\r
  73  * The one exception is on_headers_complete. In a HTTP_RESPONSE parser\r
  74  * returning '1' from on_headers_complete will tell the parser that it\r
  75  * should not expect a body. This is used when receiving a response to a\r
  76  * HEAD request which may contain 'Content-Length' or 'Transfer-Encoding:\r
  77  * chunked' headers that indicate the presence of a body.\r
  78  *\r
  79  * Returning `2` from on_headers_complete will tell parser that it should not\r
  80  * expect neither a body nor any futher responses on this connection. This is\r
  81  * useful for handling responses to a CONNECT request which may not contain\r
  82  * `Upgrade` or `Connection: upgrade` headers.\r
  83  *\r
  84  * http_data_cb does not return data chunks. It will be called arbitrarily\r
  85  * many times for each string. E.G. you might get 10 callbacks for "on_url"\r
  86  * each providing just a few characters more data.\r
  87  */\r
  88 typedef int (*http_data_cb) (http_parser*, const char *at, size_t length);\r
  89 typedef int (*http_cb) (http_parser*);\r
  90 \r
  91 \r
  92 /* Status Codes */\r
  93 #define HTTP_STATUS_MAP(XX)                                                 \\r
  94   XX(100, CONTINUE,                        Continue)                        \\r
  95   XX(101, SWITCHING_PROTOCOLS,             Switching Protocols)             \\r
  96   XX(102, PROCESSING,                      Processing)                      \\r
  97   XX(200, OK,                              OK)                              \\r
  98   XX(201, CREATED,                         Created)                         \\r
  99   XX(202, ACCEPTED,                        Accepted)                        \\r
 100   XX(203, NON_AUTHORITATIVE_INFORMATION,   Non-Authoritative Information)   \\r
 101   XX(204, NO_CONTENT,                      No Content)                      \\r
 102   XX(205, RESET_CONTENT,                   Reset Content)                   \\r
 103   XX(206, PARTIAL_CONTENT,                 Partial Content)                 \\r
 104   XX(207, MULTI_STATUS,                    Multi-Status)                    \\r
 105   XX(208, ALREADY_REPORTED,                Already Reported)                \\r
 106   XX(226, IM_USED,                         IM Used)                         \\r
 107   XX(300, MULTIPLE_CHOICES,                Multiple Choices)                \\r
 108   XX(301, MOVED_PERMANENTLY,               Moved Permanently)               \\r
 109   XX(302, FOUND,                           Found)                           \\r
 110   XX(303, SEE_OTHER,                       See Other)                       \\r
 111   XX(304, NOT_MODIFIED,                    Not Modified)                    \\r
 112   XX(305, USE_PROXY,                       Use Proxy)                       \\r
 113   XX(307, TEMPORARY_REDIRECT,              Temporary Redirect)              \\r
 114   XX(308, PERMANENT_REDIRECT,              Permanent Redirect)              \\r
 115   XX(400, BAD_REQUEST,                     Bad Request)                     \\r
 116   XX(401, UNAUTHORIZED,                    Unauthorized)                    \\r
 117   XX(402, PAYMENT_REQUIRED,                Payment Required)                \\r
 118   XX(403, FORBIDDEN,                       Forbidden)                       \\r
 119   XX(404, NOT_FOUND,                       Not Found)                       \\r
 120   XX(405, METHOD_NOT_ALLOWED,              Method Not Allowed)              \\r
 121   XX(406, NOT_ACCEPTABLE,                  Not Acceptable)                  \\r
 122   XX(407, PROXY_AUTHENTICATION_REQUIRED,   Proxy Authentication Required)   \\r
 123   XX(408, REQUEST_TIMEOUT,                 Request Timeout)                 \\r
 124   XX(409, CONFLICT,                        Conflict)                        \\r
 125   XX(410, GONE,                            Gone)                            \\r
 126   XX(411, LENGTH_REQUIRED,                 Length Required)                 \\r
 127   XX(412, PRECONDITION_FAILED,             Precondition Failed)             \\r
 128   XX(413, PAYLOAD_TOO_LARGE,               Payload Too Large)               \\r
 129   XX(414, URI_TOO_LONG,                    URI Too Long)                    \\r
 130   XX(415, UNSUPPORTED_MEDIA_TYPE,          Unsupported Media Type)          \\r
 131   XX(416, RANGE_NOT_SATISFIABLE,           Range Not Satisfiable)           \\r
 132   XX(417, EXPECTATION_FAILED,              Expectation Failed)              \\r
 133   XX(421, MISDIRECTED_REQUEST,             Misdirected Request)             \\r
 134   XX(422, UNPROCESSABLE_ENTITY,            Unprocessable Entity)            \\r
 135   XX(423, LOCKED,                          Locked)                          \\r
 136   XX(424, FAILED_DEPENDENCY,               Failed Dependency)               \\r
 137   XX(426, UPGRADE_REQUIRED,                Upgrade Required)                \\r
 138   XX(428, PRECONDITION_REQUIRED,           Precondition Required)           \\r
 139   XX(429, TOO_MANY_REQUESTS,               Too Many Requests)               \\r
 140   XX(431, REQUEST_HEADER_FIELDS_TOO_LARGE, Request Header Fields Too Large) \\r
 141   XX(451, UNAVAILABLE_FOR_LEGAL_REASONS,   Unavailable For Legal Reasons)   \\r
 142   XX(500, INTERNAL_SERVER_ERROR,           Internal Server Error)           \\r
 143   XX(501, NOT_IMPLEMENTED,                 Not Implemented)                 \\r
 144   XX(502, BAD_GATEWAY,                     Bad Gateway)                     \\r
 145   XX(503, SERVICE_UNAVAILABLE,             Service Unavailable)             \\r
 146   XX(504, GATEWAY_TIMEOUT,                 Gateway Timeout)                 \\r
 147   XX(505, HTTP_VERSION_NOT_SUPPORTED,      HTTP Version Not Supported)      \\r
 148   XX(506, VARIANT_ALSO_NEGOTIATES,         Variant Also Negotiates)         \\r
 149   XX(507, INSUFFICIENT_STORAGE,            Insufficient Storage)            \\r
 150   XX(508, LOOP_DETECTED,                   Loop Detected)                   \\r
 151   XX(510, NOT_EXTENDED,                    Not Extended)                    \\r
 152   XX(511, NETWORK_AUTHENTICATION_REQUIRED, Network Authentication Required) \\r
 153 \r
 154 enum http_status\r
 155   {\r
 156 #define XX(num, name, string) HTTP_STATUS_##name = num,\r
 157   HTTP_STATUS_MAP(XX)\r
 158 #undef XX\r
 159   };\r
 160 \r
 161 \r
 162 /* Request Methods */\r
 163 #define HTTP_METHOD_MAP(XX)         \\r
 164   XX(0,  DELETE,      DELETE)       \\r
 165   XX(1,  GET,         GET)          \\r
 166   XX(2,  HEAD,        HEAD)         \\r
 167   XX(3,  POST,        POST)         \\r
 168   XX(4,  PUT,         PUT)          \\r
 169   /* pathological */                \\r
 170   XX(5,  CONNECT,     CONNECT)      \\r
 171   XX(6,  OPTIONS,     OPTIONS)      \\r
 172   XX(7,  TRACE,       TRACE)        \\r
 173   /* WebDAV */                      \\r
 174   XX(8,  COPY,        COPY)         \\r
 175   XX(9,  LOCK,        LOCK)         \\r
 176   XX(10, MKCOL,       MKCOL)        \\r
 177   XX(11, MOVE,        MOVE)         \\r
 178   XX(12, PROPFIND,    PROPFIND)     \\r
 179   XX(13, PROPPATCH,   PROPPATCH)    \\r
 180   XX(14, SEARCH,      SEARCH)       \\r
 181   XX(15, UNLOCK,      UNLOCK)       \\r
 182   XX(16, BIND,        BIND)         \\r
 183   XX(17, REBIND,      REBIND)       \\r
 184   XX(18, UNBIND,      UNBIND)       \\r
 185   XX(19, ACL,         ACL)          \\r
 186   /* subversion */                  \\r
 187   XX(20, REPORT,      REPORT)       \\r
 188   XX(21, MKACTIVITY,  MKACTIVITY)   \\r
 189   XX(22, CHECKOUT,    CHECKOUT)     \\r
 190   XX(23, MERGE,       MERGE)        \\r
 191   /* upnp */                        \\r
 192   XX(24, MSEARCH,     M-SEARCH)     \\r
 193   XX(25, NOTIFY,      NOTIFY)       \\r
 194   XX(26, SUBSCRIBE,   SUBSCRIBE)    \\r
 195   XX(27, UNSUBSCRIBE, UNSUBSCRIBE)  \\r
 196   /* RFC-5789 */                    \\r
 197   XX(28, PATCH,       PATCH)        \\r
 198   XX(29, PURGE,       PURGE)        \\r
 199   /* CalDAV */                      \\r
 200   XX(30, MKCALENDAR,  MKCALENDAR)   \\r
 201   /* RFC-2068, section 19.6.1.2 */  \\r
 202   XX(31, LINK,        LINK)         \\r
 203   XX(32, UNLINK,      UNLINK)       \\r
 204   /* icecast */                     \\r
 205   XX(33, SOURCE,      SOURCE)       \\r
 206 \r
 207 enum http_method\r
 208   {\r
 209 #define XX(num, name, string) HTTP_##name = num,\r
 210   HTTP_METHOD_MAP(XX)\r
 211 #undef XX\r
 212   };\r
 213 \r
 214 \r
 215 enum http_parser_type { HTTP_REQUEST, HTTP_RESPONSE, HTTP_BOTH };\r
 216 \r
 217 \r
 218 /* Flag values for http_parser.flags field */\r
 219 enum flags\r
 220   { F_CHUNKED               = 1 << 0\r
 221   , F_CONNECTION_KEEP_ALIVE = 1 << 1\r
 222   , F_CONNECTION_CLOSE      = 1 << 2\r
 223   , F_CONNECTION_UPGRADE    = 1 << 3\r
 224   , F_TRAILING              = 1 << 4\r
 225   , F_UPGRADE               = 1 << 5\r
 226   , F_SKIPBODY              = 1 << 6\r
 227   , F_CONTENTLENGTH         = 1 << 7\r
 228   };\r
 229 \r
 230 \r
 231 /* Map for errno-related constants\r
 232  *\r
 233  * The provided argument should be a macro that takes 2 arguments.\r
 234  */\r
 235 #define HTTP_ERRNO_MAP(XX)                                           \\r
 236   /* No error */                                                     \\r
 237   XX(OK, "success")                                                  \\r
 238                                                                      \\r
 239   /* Callback-related errors */                                      \\r
 240   XX(CB_message_begin, "the on_message_begin callback failed")       \\r
 241   XX(CB_url, "the on_url callback failed")                           \\r
 242   XX(CB_header_field, "the on_header_field callback failed")         \\r
 243   XX(CB_header_value, "the on_header_value callback failed")         \\r
 244   XX(CB_headers_complete, "the on_headers_complete callback failed") \\r
 245   XX(CB_body, "the on_body callback failed")                         \\r
 246   XX(CB_message_complete, "the on_message_complete callback failed") \\r
 247   XX(CB_status, "the on_status callback failed")                     \\r
 248   XX(CB_chunk_header, "the on_chunk_header callback failed")         \\r
 249   XX(CB_chunk_complete, "the on_chunk_complete callback failed")     \\r
 250                                                                      \\r
 251   /* Parsing-related errors */                                       \\r
 252   XX(INVALID_EOF_STATE, "stream ended at an unexpected time")        \\r
 253   XX(HEADER_OVERFLOW,                                                \\r
 254      "too many header bytes seen; overflow detected")                \\r
 255   XX(CLOSED_CONNECTION,                                              \\r
 256      "data received after completed connection: close message")      \\r
 257   XX(INVALID_VERSION, "invalid HTTP version")                        \\r
 258   XX(INVALID_STATUS, "invalid HTTP status code")                     \\r
 259   XX(INVALID_METHOD, "invalid HTTP method")                          \\r
 260   XX(INVALID_URL, "invalid URL")                                     \\r
 261   XX(INVALID_HOST, "invalid host")                                   \\r
 262   XX(INVALID_PORT, "invalid port")                                   \\r
 263   XX(INVALID_PATH, "invalid path")                                   \\r
 264   XX(INVALID_QUERY_STRING, "invalid query string")                   \\r
 265   XX(INVALID_FRAGMENT, "invalid fragment")                           \\r
 266   XX(LF_EXPECTED, "LF character expected")                           \\r
 267   XX(INVALID_HEADER_TOKEN, "invalid character in header")            \\r
 268   XX(INVALID_CONTENT_LENGTH,                                         \\r
 269      "invalid character in content-length header")                   \\r
 270   XX(UNEXPECTED_CONTENT_LENGTH,                                      \\r
 271      "unexpected content-length header")                             \\r
 272   XX(INVALID_CHUNK_SIZE,                                             \\r
 273      "invalid character in chunk size header")                       \\r
 274   XX(INVALID_CONSTANT, "invalid constant string")                    \\r
 275   XX(INVALID_INTERNAL_STATE, "encountered unexpected internal state")\\r
 276   XX(STRICT, "strict mode assertion failed")                         \\r
 277   XX(PAUSED, "parser is paused")                                     \\r
 278   XX(UNKNOWN, "an unknown error occurred")\r
 279 \r
 280 \r
 281 /* Define HPE_* values for each errno value above */\r
 282 #define HTTP_ERRNO_GEN(n, s) HPE_##n,\r
 283 enum http_errno {\r
 284   HTTP_ERRNO_MAP(HTTP_ERRNO_GEN)\r
 285 };\r
 286 #undef HTTP_ERRNO_GEN\r
 287 \r
 288 \r
 289 /* Get an http_errno value from an http_parser */\r
 290 #define HTTP_PARSER_ERRNO(p)            ((enum http_errno) (p)->http_errno)\r
 291 \r
 292 \r
 293 struct http_parser {\r
 294   /** PRIVATE **/\r
 295   unsigned int type : 2;         /* enum http_parser_type */\r
 296   unsigned int flags : 8;        /* F_* values from 'flags' enum; semi-public */\r
 297   unsigned int state : 7;        /* enum state from http_parser.c */\r
 298   unsigned int header_state : 7; /* enum header_state from http_parser.c */\r
 299   unsigned int index : 7;        /* index into current matcher */\r
 300   unsigned int lenient_http_headers : 1;\r
 301 \r
 302   uint32_t nread;          /* # bytes read in various scenarios */\r
 303   uint64_t content_length; /* # bytes in body (0 if no Content-Length header) */\r
 304 \r
 305   /** READ-ONLY **/\r
 306   unsigned short http_major;\r
 307   unsigned short http_minor;\r
 308   unsigned int status_code : 16; /* responses only */\r
 309   unsigned int method : 8;       /* requests only */\r
 310   unsigned int http_errno : 7;\r
 311 \r
 312   /* 1 = Upgrade header was present and the parser has exited because of that.\r
 313    * 0 = No upgrade header present.\r
 314    * Should be checked when http_parser_execute() returns in addition to\r
 315    * error checking.\r
 316    */\r
 317   unsigned int upgrade : 1;\r
 318 \r
 319   /** PUBLIC **/\r
 320   void *data; /* A pointer to get hook to the "connection" or "socket" object */\r
 321 };\r
 322 \r
 323 \r
 324 struct http_parser_settings {\r
 325   http_cb      on_message_begin;\r
 326   http_data_cb on_url;\r
 327   http_data_cb on_status;\r
 328   http_data_cb on_header_field;\r
 329   http_data_cb on_header_value;\r
 330   http_cb      on_headers_complete;\r
 331   http_data_cb on_body;\r
 332   http_cb      on_message_complete;\r
 333   /* When on_chunk_header is called, the current chunk length is stored\r
 334    * in parser->content_length.\r
 335    */\r
 336   http_cb      on_chunk_header;\r
 337   http_cb      on_chunk_complete;\r
 338 };\r
 339 \r
 340 \r
 341 enum http_parser_url_fields\r
 342   { UF_SCHEMA           = 0\r
 343   , UF_HOST             = 1\r
 344   , UF_PORT             = 2\r
 345   , UF_PATH             = 3\r
 346   , UF_QUERY            = 4\r
 347   , UF_FRAGMENT         = 5\r
 348   , UF_USERINFO         = 6\r
 349   , UF_MAX              = 7\r
 350   };\r
 351 \r
 352 \r
 353 /* Result structure for http_parser_parse_url().\r
 354  *\r
 355  * Callers should index into field_data[] with UF_* values iff field_set\r
 356  * has the relevant (1 << UF_*) bit set. As a courtesy to clients (and\r
 357  * because we probably have padding left over), we convert any port to\r
 358  * a uint16_t.\r
 359  */\r
 360 struct http_parser_url {\r
 361   uint16_t field_set;           /* Bitmask of (1 << UF_*) values */\r
 362   uint16_t port;                /* Converted UF_PORT string */\r
 363 \r
 364   struct {\r
 365     uint16_t off;               /* Offset into buffer in which field starts */\r
 366     uint16_t len;               /* Length of run in buffer */\r
 367   } field_data[UF_MAX];\r
 368 };\r
 369 \r
 370 \r
 371 /* Returns the library version. Bits 16-23 contain the major version number,\r
 372  * bits 8-15 the minor version number and bits 0-7 the patch level.\r
 373  * Usage example:\r
 374  *\r
 375  *   unsigned long version = http_parser_version();\r
 376  *   unsigned major = (version >> 16) & 255;\r
 377  *   unsigned minor = (version >> 8) & 255;\r
 378  *   unsigned patch = version & 255;\r
 379  *   printf("http_parser v%u.%u.%u\n", major, minor, patch);\r
 380  */\r
 381 unsigned long http_parser_version(void);\r
 382 \r
 383 void http_parser_init(http_parser *parser, enum http_parser_type type);\r
 384 \r
 385 \r
 386 /* Initialize http_parser_settings members to 0\r
 387  */\r
 388 void http_parser_settings_init(http_parser_settings *settings);\r
 389 \r
 390 \r
 391 /* Executes the parser. Returns number of parsed bytes. Sets\r
 392  * `parser->http_errno` on error. */\r
 393 size_t http_parser_execute(http_parser *parser,\r
 394                            const http_parser_settings *settings,\r
 395                            const char *data,\r
 396                            size_t len);\r
 397 \r
 398 \r
 399 /* If http_should_keep_alive() in the on_headers_complete or\r
 400  * on_message_complete callback returns 0, then this should be\r
 401  * the last message on the connection.\r
 402  * If you are the server, respond with the "Connection: close" header.\r
 403  * If you are the client, close the connection.\r
 404  */\r
 405 int http_should_keep_alive(const http_parser *parser);\r
 406 \r
 407 /* Returns a string version of the HTTP method. */\r
 408 const char *http_method_str(enum http_method m);\r
 409 \r
 410 /* Returns a string version of the HTTP status code. */\r
 411 const char *http_status_str(enum http_status s);\r
 412 \r
 413 /* Return a string name of the given error */\r
 414 const char *http_errno_name(enum http_errno err);\r
 415 \r
 416 /* Return a string description of the given error */\r
 417 const char *http_errno_description(enum http_errno err);\r
 418 \r
 419 /* Initialize all http_parser_url members to 0 */\r
 420 void http_parser_url_init(struct http_parser_url *u);\r
 421 \r
 422 /* Parse a URL; return nonzero on failure */\r
 423 int http_parser_parse_url(const char *buf, size_t buflen,\r
 424                           int is_connect,\r
 425                           struct http_parser_url *u);\r
 426 \r
 427 /* Pause or un-pause the parser; a nonzero value pauses */\r
 428 void http_parser_pause(http_parser *parser, int paused);\r
 429 \r
 430 /* Checks if this is the final chunk of the body. */\r
 431 int http_body_is_final(const http_parser *parser);\r
 432 \r
 433 /* Change the maximum header size provided at compile time. */\r
 434 void http_parser_set_max_header_size(uint32_t size);\r
 435 \r
 436 #ifdef __cplusplus\r
 437 }\r
 438 #endif\r
 439 #endif\r