third-party/llhttp/include/llhttp.h

   1 #ifndef INCLUDE_LLHTTP_H_
   2 #define INCLUDE_LLHTTP_H_
   3
   4 #define LLHTTP_VERSION_MAJOR 2
   5 #define LLHTTP_VERSION_MINOR 0
   6 #define LLHTTP_VERSION_PATCH 4
   7
   8 #ifndef INCLUDE_LLHTTP_ITSELF_H_
   9 #define INCLUDE_LLHTTP_ITSELF_H_
  10 #ifdef __cplusplus
  11 extern "C" {
  12 #endif
  13
  14 #include <stdint.h>
  15
  16 typedef struct llhttp__internal_s llhttp__internal_t;
  17 struct llhttp__internal_s {
  18   int32_t _index;
  19   void* _span_pos0;
  20   void* _span_cb0;
  21   int32_t error;
  22   const char* reason;
  23   const char* error_pos;
  24   void* data;
  25   void* _current;
  26   uint64_t content_length;
  27   uint8_t type;
  28   uint8_t method;
  29   uint8_t http_major;
  30   uint8_t http_minor;
  31   uint8_t header_state;
  32   uint16_t flags;
  33   uint8_t upgrade;
  34   uint16_t status_code;
  35   uint8_t finish;
  36   void* settings;
  37 };
  38
  39 int llhttp__internal_init(llhttp__internal_t* s);
  40 int llhttp__internal_execute(llhttp__internal_t* s, const char* p, const char* endp);
  41
  42 #ifdef __cplusplus
  43 }  /* extern "C" */
  44 #endif
  45 #endif  /* INCLUDE_LLHTTP_ITSELF_H_ */
  46
  47 #ifndef LLLLHTTP_C_HEADERS_
  48 #define LLLLHTTP_C_HEADERS_
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 enum llhttp_errno {
  54   HPE_OK = 0,
  55   HPE_INTERNAL = 1,
  56   HPE_STRICT = 2,
  57   HPE_LF_EXPECTED = 3,
  58   HPE_UNEXPECTED_CONTENT_LENGTH = 4,
  59   HPE_CLOSED_CONNECTION = 5,
  60   HPE_INVALID_METHOD = 6,
  61   HPE_INVALID_URL = 7,
  62   HPE_INVALID_CONSTANT = 8,
  63   HPE_INVALID_VERSION = 9,
  64   HPE_INVALID_HEADER_TOKEN = 10,
  65   HPE_INVALID_CONTENT_LENGTH = 11,
  66   HPE_INVALID_CHUNK_SIZE = 12,
  67   HPE_INVALID_STATUS = 13,
  68   HPE_INVALID_EOF_STATE = 14,
  69   HPE_INVALID_TRANSFER_ENCODING = 15,
  70   HPE_CB_MESSAGE_BEGIN = 16,
  71   HPE_CB_HEADERS_COMPLETE = 17,
  72   HPE_CB_MESSAGE_COMPLETE = 18,
  73   HPE_CB_CHUNK_HEADER = 19,
  74   HPE_CB_CHUNK_COMPLETE = 20,
  75   HPE_PAUSED = 21,
  76   HPE_PAUSED_UPGRADE = 22,
  77   HPE_USER = 23
  78 };
  79 typedef enum llhttp_errno llhttp_errno_t;
  80
  81 enum llhttp_flags {
  82   F_CONNECTION_KEEP_ALIVE = 0x1,
  83   F_CONNECTION_CLOSE = 0x2,
  84   F_CONNECTION_UPGRADE = 0x4,
  85   F_CHUNKED = 0x8,
  86   F_UPGRADE = 0x10,
  87   F_CONTENT_LENGTH = 0x20,
  88   F_SKIPBODY = 0x40,
  89   F_TRAILING = 0x80,
  90   F_LENIENT = 0x100,
  91   F_TRANSFER_ENCODING = 0x200
  92 };
  93 typedef enum llhttp_flags llhttp_flags_t;
  94
  95 enum llhttp_type {
  96   HTTP_BOTH = 0,
  97   HTTP_REQUEST = 1,
  98   HTTP_RESPONSE = 2
  99 };
 100 typedef enum llhttp_type llhttp_type_t;
 101
 102 enum llhttp_finish {
 103   HTTP_FINISH_SAFE = 0,
 104   HTTP_FINISH_SAFE_WITH_CB = 1,
 105   HTTP_FINISH_UNSAFE = 2
 106 };
 107 typedef enum llhttp_finish llhttp_finish_t;
 108
 109 enum llhttp_method {
 110   HTTP_DELETE = 0,
 111   HTTP_GET = 1,
 112   HTTP_HEAD = 2,
 113   HTTP_POST = 3,
 114   HTTP_PUT = 4,
 115   HTTP_CONNECT = 5,
 116   HTTP_OPTIONS = 6,
 117   HTTP_TRACE = 7,
 118   HTTP_COPY = 8,
 119   HTTP_LOCK = 9,
 120   HTTP_MKCOL = 10,
 121   HTTP_MOVE = 11,
 122   HTTP_PROPFIND = 12,
 123   HTTP_PROPPATCH = 13,
 124   HTTP_SEARCH = 14,
 125   HTTP_UNLOCK = 15,
 126   HTTP_BIND = 16,
 127   HTTP_REBIND = 17,
 128   HTTP_UNBIND = 18,
 129   HTTP_ACL = 19,
 130   HTTP_REPORT = 20,
 131   HTTP_MKACTIVITY = 21,
 132   HTTP_CHECKOUT = 22,
 133   HTTP_MERGE = 23,
 134   HTTP_MSEARCH = 24,
 135   HTTP_NOTIFY = 25,
 136   HTTP_SUBSCRIBE = 26,
 137   HTTP_UNSUBSCRIBE = 27,
 138   HTTP_PATCH = 28,
 139   HTTP_PURGE = 29,
 140   HTTP_MKCALENDAR = 30,
 141   HTTP_LINK = 31,
 142   HTTP_UNLINK = 32,
 143   HTTP_SOURCE = 33
 144 };
 145 typedef enum llhttp_method llhttp_method_t;
 146
 147 #define HTTP_ERRNO_MAP(XX) \
 148   XX(0, OK, OK) \
 149   XX(1, INTERNAL, INTERNAL) \
 150   XX(2, STRICT, STRICT) \
 151   XX(3, LF_EXPECTED, LF_EXPECTED) \
 152   XX(4, UNEXPECTED_CONTENT_LENGTH, UNEXPECTED_CONTENT_LENGTH) \
 153   XX(5, CLOSED_CONNECTION, CLOSED_CONNECTION) \
 154   XX(6, INVALID_METHOD, INVALID_METHOD) \
 155   XX(7, INVALID_URL, INVALID_URL) \
 156   XX(8, INVALID_CONSTANT, INVALID_CONSTANT) \
 157   XX(9, INVALID_VERSION, INVALID_VERSION) \
 158   XX(10, INVALID_HEADER_TOKEN, INVALID_HEADER_TOKEN) \
 159   XX(11, INVALID_CONTENT_LENGTH, INVALID_CONTENT_LENGTH) \
 160   XX(12, INVALID_CHUNK_SIZE, INVALID_CHUNK_SIZE) \
 161   XX(13, INVALID_STATUS, INVALID_STATUS) \
 162   XX(14, INVALID_EOF_STATE, INVALID_EOF_STATE) \
 163   XX(15, INVALID_TRANSFER_ENCODING, INVALID_TRANSFER_ENCODING) \
 164   XX(16, CB_MESSAGE_BEGIN, CB_MESSAGE_BEGIN) \
 165   XX(17, CB_HEADERS_COMPLETE, CB_HEADERS_COMPLETE) \
 166   XX(18, CB_MESSAGE_COMPLETE, CB_MESSAGE_COMPLETE) \
 167   XX(19, CB_CHUNK_HEADER, CB_CHUNK_HEADER) \
 168   XX(20, CB_CHUNK_COMPLETE, CB_CHUNK_COMPLETE) \
 169   XX(21, PAUSED, PAUSED) \
 170   XX(22, PAUSED_UPGRADE, PAUSED_UPGRADE) \
 171   XX(23, USER, USER) \
 172
 173
 174 #define HTTP_METHOD_MAP(XX) \
 175   XX(0, DELETE, DELETE) \
 176   XX(1, GET, GET) \
 177   XX(2, HEAD, HEAD) \
 178   XX(3, POST, POST) \
 179   XX(4, PUT, PUT) \
 180   XX(5, CONNECT, CONNECT) \
 181   XX(6, OPTIONS, OPTIONS) \
 182   XX(7, TRACE, TRACE) \
 183   XX(8, COPY, COPY) \
 184   XX(9, LOCK, LOCK) \
 185   XX(10, MKCOL, MKCOL) \
 186   XX(11, MOVE, MOVE) \
 187   XX(12, PROPFIND, PROPFIND) \
 188   XX(13, PROPPATCH, PROPPATCH) \
 189   XX(14, SEARCH, SEARCH) \
 190   XX(15, UNLOCK, UNLOCK) \
 191   XX(16, BIND, BIND) \
 192   XX(17, REBIND, REBIND) \
 193   XX(18, UNBIND, UNBIND) \
 194   XX(19, ACL, ACL) \
 195   XX(20, REPORT, REPORT) \
 196   XX(21, MKACTIVITY, MKACTIVITY) \
 197   XX(22, CHECKOUT, CHECKOUT) \
 198   XX(23, MERGE, MERGE) \
 199   XX(24, MSEARCH, M-SEARCH) \
 200   XX(25, NOTIFY, NOTIFY) \
 201   XX(26, SUBSCRIBE, SUBSCRIBE) \
 202   XX(27, UNSUBSCRIBE, UNSUBSCRIBE) \
 203   XX(28, PATCH, PATCH) \
 204   XX(29, PURGE, PURGE) \
 205   XX(30, MKCALENDAR, MKCALENDAR) \
 206   XX(31, LINK, LINK) \
 207   XX(32, UNLINK, UNLINK) \
 208   XX(33, SOURCE, SOURCE) \
 209
 210
 211
 212 #ifdef __cplusplus
 213 }  /* extern "C" */
 214 #endif
 215 #endif  /* LLLLHTTP_C_HEADERS_ */
 216
 217 #ifndef INCLUDE_LLHTTP_API_H_
 218 #define INCLUDE_LLHTTP_API_H_
 219 #ifdef __cplusplus
 220 extern "C" {
 221 #endif
 222 #include <stddef.h>
 223
 224 typedef llhttp__internal_t llhttp_t;
 225 typedef struct llhttp_settings_s llhttp_settings_t;
 226
 227 typedef int (*llhttp_data_cb)(llhttp_t*, const char *at, size_t length);
 228 typedef int (*llhttp_cb)(llhttp_t*);
 229
 230 struct llhttp_settings_s {
 231   /* Possible return values 0, -1, `HPE_PAUSED` */
 232   llhttp_cb      on_message_begin;
 233
 234   llhttp_data_cb on_url;
 235   llhttp_data_cb on_status;
 236   llhttp_data_cb on_header_field;
 237   llhttp_data_cb on_header_value;
 238
 239   /* Possible return values:
 240    * 0  - Proceed normally
 241    * 1  - Assume that request/response has no body, and proceed to parsing the
 242    *      next message
 243    * 2  - Assume absence of body (as above) and make `llhttp_execute()` return
 244    *      `HPE_PAUSED_UPGRADE`
 245    * -1 - Error
 246    * `HPE_PAUSED`
 247    */
 248   llhttp_cb      on_headers_complete;
 249
 250   llhttp_data_cb on_body;
 251
 252   /* Possible return values 0, -1, `HPE_PAUSED` */
 253   llhttp_cb      on_message_complete;
 254
 255   /* When on_chunk_header is called, the current chunk length is stored
 256    * in parser->content_length.
 257    * Possible return values 0, -1, `HPE_PAUSED`
 258    */
 259   llhttp_cb      on_chunk_header;
 260   llhttp_cb      on_chunk_complete;
 261 };
 262
 263 /* Initialize the parser with specific type and user settings */
 264 void llhttp_init(llhttp_t* parser, llhttp_type_t type,
 265                  const llhttp_settings_t* settings);
 266
 267 /* Initialize the settings object */
 268 void llhttp_settings_init(llhttp_settings_t* settings);
 269
 270 /* Parse full or partial request/response, invoking user callbacks along the
 271  * way.
 272  *
 273  * If any of `llhttp_data_cb` returns errno not equal to `HPE_OK` - the parsing
 274  * interrupts, and such errno is returned from `llhttp_execute()`. If
 275  * `HPE_PAUSED` was used as a errno, the execution can be resumed with
 276  * `llhttp_resume()` call.
 277  *
 278  * In a special case of CONNECT/Upgrade request/response `HPE_PAUSED_UPGRADE`
 279  * is returned after fully parsing the request/response. If the user wishes to
 280  * continue parsing, they need to invoke `llhttp_resume_after_upgrade()`.
 281  *
 282  * NOTE: if this function ever returns a non-pause type error, it will continue
 283  * to return the same error upon each successive call up until `llhttp_init()`
 284  * is called.
 285  */
 286 llhttp_errno_t llhttp_execute(llhttp_t* parser, const char* data, size_t len);
 287
 288 /* This method should be called when the other side has no further bytes to
 289  * send (e.g. shutdown of readable side of the TCP connection.)
 290  *
 291  * Requests without `Content-Length` and other messages might require treating
 292  * all incoming bytes as the part of the body, up to the last byte of the
 293  * connection. This method will invoke `on_message_complete()` callback if the
 294  * request was terminated safely. Otherwise a error code would be returned.
 295  */
 296 llhttp_errno_t llhttp_finish(llhttp_t* parser);
 297
 298 /* Returns `1` if the incoming message is parsed until the last byte, and has
 299  * to be completed by calling `llhttp_finish()` on EOF
 300  */
 301 int llhttp_message_needs_eof(const llhttp_t* parser);
 302
 303 /* Returns `1` if there might be any other messages following the last that was
 304  * successfully parsed.
 305  */
 306 int llhttp_should_keep_alive(const llhttp_t* parser);
 307
 308 /* Make further calls of `llhttp_execute()` return `HPE_PAUSED` and set
 309  * appropriate error reason.
 310  *
 311  * Important: do not call this from user callbacks! User callbacks must return
 312  * `HPE_PAUSED` if pausing is required.
 313  */
 314 void llhttp_pause(llhttp_t* parser);
 315
 316 /* Might be called to resume the execution after the pause in user's callback.
 317  * See `llhttp_execute()` above for details.
 318  *
 319  * Call this only if `llhttp_execute()` returns `HPE_PAUSED`.
 320  */
 321 void llhttp_resume(llhttp_t* parser);
 322
 323 /* Might be called to resume the execution after the pause in user's callback.
 324  * See `llhttp_execute()` above for details.
 325  *
 326  * Call this only if `llhttp_execute()` returns `HPE_PAUSED_UPGRADE`
 327  */
 328 void llhttp_resume_after_upgrade(llhttp_t* parser);
 329
 330 /* Returns the latest return error */
 331 llhttp_errno_t llhttp_get_errno(const llhttp_t* parser);
 332
 333 /* Returns the verbal explanation of the latest returned error.
 334  *
 335  * Note: User callback should set error reason when returning the error. See
 336  * `llhttp_set_error_reason()` for details.
 337  */
 338 const char* llhttp_get_error_reason(const llhttp_t* parser);
 339
 340 /* Assign verbal description to the returned error. Must be called in user
 341  * callbacks right before returning the errno.
 342  *
 343  * Note: `HPE_USER` error code might be useful in user callbacks.
 344  */
 345 void llhttp_set_error_reason(llhttp_t* parser, const char* reason);
 346
 347 /* Returns the pointer to the last parsed byte before the returned error. The
 348  * pointer is relative to the `data` argument of `llhttp_execute()`.
 349  *
 350  * Note: this method might be useful for counting the number of parsed bytes.
 351  */
 352 const char* llhttp_get_error_pos(const llhttp_t* parser);
 353
 354 /* Returns textual name of error code */
 355 const char* llhttp_errno_name(llhttp_errno_t err);
 356
 357 /* Returns textual name of HTTP method */
 358 const char* llhttp_method_name(llhttp_method_t method);
 359
 360
 361 /* Enables/disables lenient header value parsing (disabled by default).
 362  *
 363  * Lenient parsing disables header value token checks, extending llhttp's
 364  * protocol support to highly non-compliant clients/server. No
 365  * `HPE_INVALID_HEADER_TOKEN` will be raised for incorrect header values when
 366  * lenient parsing is "on".
 367  *
 368  * **(USE AT YOUR OWN RISK)**
 369  */
 370 void llhttp_set_lenient(llhttp_t* parser, int enabled);
 371
 372 #ifdef __cplusplus
 373 }  /* extern "C" */
 374 #endif
 375 #endif  /* INCLUDE_LLHTTP_API_H_ */
 376
 377 #endif  /* INCLUDE_LLHTTP_H_ */