Upgrade to 1.46.0
[platform/upstream/nghttp2.git] / third-party / llhttp / include / llhttp.h
1 #ifndef INCLUDE_LLHTTP_H_
2 #define INCLUDE_LLHTTP_H_
3
4 #define LLHTTP_VERSION_MAJOR 6
5 #define LLHTTP_VERSION_MINOR 0
6 #define LLHTTP_VERSION_PATCH 2
7
8 #ifndef LLHTTP_STRICT_MODE
9 # define LLHTTP_STRICT_MODE 0
10 #endif
11
12 #ifndef INCLUDE_LLHTTP_ITSELF_H_
13 #define INCLUDE_LLHTTP_ITSELF_H_
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 #include <stdint.h>
19
20 typedef struct llhttp__internal_s llhttp__internal_t;
21 struct llhttp__internal_s {
22   int32_t _index;
23   void* _span_pos0;
24   void* _span_cb0;
25   int32_t error;
26   const char* reason;
27   const char* error_pos;
28   void* data;
29   void* _current;
30   uint64_t content_length;
31   uint8_t type;
32   uint8_t method;
33   uint8_t http_major;
34   uint8_t http_minor;
35   uint8_t header_state;
36   uint8_t lenient_flags;
37   uint8_t upgrade;
38   uint8_t finish;
39   uint16_t flags;
40   uint16_t status_code;
41   void* settings;
42 };
43
44 int llhttp__internal_init(llhttp__internal_t* s);
45 int llhttp__internal_execute(llhttp__internal_t* s, const char* p, const char* endp);
46
47 #ifdef __cplusplus
48 }  /* extern "C" */
49 #endif
50 #endif  /* INCLUDE_LLHTTP_ITSELF_H_ */
51
52 #ifndef LLLLHTTP_C_HEADERS_
53 #define LLLLHTTP_C_HEADERS_
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57
58 enum llhttp_errno {
59   HPE_OK = 0,
60   HPE_INTERNAL = 1,
61   HPE_STRICT = 2,
62   HPE_LF_EXPECTED = 3,
63   HPE_UNEXPECTED_CONTENT_LENGTH = 4,
64   HPE_CLOSED_CONNECTION = 5,
65   HPE_INVALID_METHOD = 6,
66   HPE_INVALID_URL = 7,
67   HPE_INVALID_CONSTANT = 8,
68   HPE_INVALID_VERSION = 9,
69   HPE_INVALID_HEADER_TOKEN = 10,
70   HPE_INVALID_CONTENT_LENGTH = 11,
71   HPE_INVALID_CHUNK_SIZE = 12,
72   HPE_INVALID_STATUS = 13,
73   HPE_INVALID_EOF_STATE = 14,
74   HPE_INVALID_TRANSFER_ENCODING = 15,
75   HPE_CB_MESSAGE_BEGIN = 16,
76   HPE_CB_HEADERS_COMPLETE = 17,
77   HPE_CB_MESSAGE_COMPLETE = 18,
78   HPE_CB_CHUNK_HEADER = 19,
79   HPE_CB_CHUNK_COMPLETE = 20,
80   HPE_PAUSED = 21,
81   HPE_PAUSED_UPGRADE = 22,
82   HPE_PAUSED_H2_UPGRADE = 23,
83   HPE_USER = 24
84 };
85 typedef enum llhttp_errno llhttp_errno_t;
86
87 enum llhttp_flags {
88   F_CONNECTION_KEEP_ALIVE = 0x1,
89   F_CONNECTION_CLOSE = 0x2,
90   F_CONNECTION_UPGRADE = 0x4,
91   F_CHUNKED = 0x8,
92   F_UPGRADE = 0x10,
93   F_CONTENT_LENGTH = 0x20,
94   F_SKIPBODY = 0x40,
95   F_TRAILING = 0x80,
96   F_TRANSFER_ENCODING = 0x200
97 };
98 typedef enum llhttp_flags llhttp_flags_t;
99
100 enum llhttp_lenient_flags {
101   LENIENT_HEADERS = 0x1,
102   LENIENT_CHUNKED_LENGTH = 0x2,
103   LENIENT_KEEP_ALIVE = 0x4
104 };
105 typedef enum llhttp_lenient_flags llhttp_lenient_flags_t;
106
107 enum llhttp_type {
108   HTTP_BOTH = 0,
109   HTTP_REQUEST = 1,
110   HTTP_RESPONSE = 2
111 };
112 typedef enum llhttp_type llhttp_type_t;
113
114 enum llhttp_finish {
115   HTTP_FINISH_SAFE = 0,
116   HTTP_FINISH_SAFE_WITH_CB = 1,
117   HTTP_FINISH_UNSAFE = 2
118 };
119 typedef enum llhttp_finish llhttp_finish_t;
120
121 enum llhttp_method {
122   HTTP_DELETE = 0,
123   HTTP_GET = 1,
124   HTTP_HEAD = 2,
125   HTTP_POST = 3,
126   HTTP_PUT = 4,
127   HTTP_CONNECT = 5,
128   HTTP_OPTIONS = 6,
129   HTTP_TRACE = 7,
130   HTTP_COPY = 8,
131   HTTP_LOCK = 9,
132   HTTP_MKCOL = 10,
133   HTTP_MOVE = 11,
134   HTTP_PROPFIND = 12,
135   HTTP_PROPPATCH = 13,
136   HTTP_SEARCH = 14,
137   HTTP_UNLOCK = 15,
138   HTTP_BIND = 16,
139   HTTP_REBIND = 17,
140   HTTP_UNBIND = 18,
141   HTTP_ACL = 19,
142   HTTP_REPORT = 20,
143   HTTP_MKACTIVITY = 21,
144   HTTP_CHECKOUT = 22,
145   HTTP_MERGE = 23,
146   HTTP_MSEARCH = 24,
147   HTTP_NOTIFY = 25,
148   HTTP_SUBSCRIBE = 26,
149   HTTP_UNSUBSCRIBE = 27,
150   HTTP_PATCH = 28,
151   HTTP_PURGE = 29,
152   HTTP_MKCALENDAR = 30,
153   HTTP_LINK = 31,
154   HTTP_UNLINK = 32,
155   HTTP_SOURCE = 33,
156   HTTP_PRI = 34,
157   HTTP_DESCRIBE = 35,
158   HTTP_ANNOUNCE = 36,
159   HTTP_SETUP = 37,
160   HTTP_PLAY = 38,
161   HTTP_PAUSE = 39,
162   HTTP_TEARDOWN = 40,
163   HTTP_GET_PARAMETER = 41,
164   HTTP_SET_PARAMETER = 42,
165   HTTP_REDIRECT = 43,
166   HTTP_RECORD = 44,
167   HTTP_FLUSH = 45
168 };
169 typedef enum llhttp_method llhttp_method_t;
170
171 #define HTTP_ERRNO_MAP(XX) \
172   XX(0, OK, OK) \
173   XX(1, INTERNAL, INTERNAL) \
174   XX(2, STRICT, STRICT) \
175   XX(3, LF_EXPECTED, LF_EXPECTED) \
176   XX(4, UNEXPECTED_CONTENT_LENGTH, UNEXPECTED_CONTENT_LENGTH) \
177   XX(5, CLOSED_CONNECTION, CLOSED_CONNECTION) \
178   XX(6, INVALID_METHOD, INVALID_METHOD) \
179   XX(7, INVALID_URL, INVALID_URL) \
180   XX(8, INVALID_CONSTANT, INVALID_CONSTANT) \
181   XX(9, INVALID_VERSION, INVALID_VERSION) \
182   XX(10, INVALID_HEADER_TOKEN, INVALID_HEADER_TOKEN) \
183   XX(11, INVALID_CONTENT_LENGTH, INVALID_CONTENT_LENGTH) \
184   XX(12, INVALID_CHUNK_SIZE, INVALID_CHUNK_SIZE) \
185   XX(13, INVALID_STATUS, INVALID_STATUS) \
186   XX(14, INVALID_EOF_STATE, INVALID_EOF_STATE) \
187   XX(15, INVALID_TRANSFER_ENCODING, INVALID_TRANSFER_ENCODING) \
188   XX(16, CB_MESSAGE_BEGIN, CB_MESSAGE_BEGIN) \
189   XX(17, CB_HEADERS_COMPLETE, CB_HEADERS_COMPLETE) \
190   XX(18, CB_MESSAGE_COMPLETE, CB_MESSAGE_COMPLETE) \
191   XX(19, CB_CHUNK_HEADER, CB_CHUNK_HEADER) \
192   XX(20, CB_CHUNK_COMPLETE, CB_CHUNK_COMPLETE) \
193   XX(21, PAUSED, PAUSED) \
194   XX(22, PAUSED_UPGRADE, PAUSED_UPGRADE) \
195   XX(23, PAUSED_H2_UPGRADE, PAUSED_H2_UPGRADE) \
196   XX(24, USER, USER) \
197
198
199 #define HTTP_METHOD_MAP(XX) \
200   XX(0, DELETE, DELETE) \
201   XX(1, GET, GET) \
202   XX(2, HEAD, HEAD) \
203   XX(3, POST, POST) \
204   XX(4, PUT, PUT) \
205   XX(5, CONNECT, CONNECT) \
206   XX(6, OPTIONS, OPTIONS) \
207   XX(7, TRACE, TRACE) \
208   XX(8, COPY, COPY) \
209   XX(9, LOCK, LOCK) \
210   XX(10, MKCOL, MKCOL) \
211   XX(11, MOVE, MOVE) \
212   XX(12, PROPFIND, PROPFIND) \
213   XX(13, PROPPATCH, PROPPATCH) \
214   XX(14, SEARCH, SEARCH) \
215   XX(15, UNLOCK, UNLOCK) \
216   XX(16, BIND, BIND) \
217   XX(17, REBIND, REBIND) \
218   XX(18, UNBIND, UNBIND) \
219   XX(19, ACL, ACL) \
220   XX(20, REPORT, REPORT) \
221   XX(21, MKACTIVITY, MKACTIVITY) \
222   XX(22, CHECKOUT, CHECKOUT) \
223   XX(23, MERGE, MERGE) \
224   XX(24, MSEARCH, M-SEARCH) \
225   XX(25, NOTIFY, NOTIFY) \
226   XX(26, SUBSCRIBE, SUBSCRIBE) \
227   XX(27, UNSUBSCRIBE, UNSUBSCRIBE) \
228   XX(28, PATCH, PATCH) \
229   XX(29, PURGE, PURGE) \
230   XX(30, MKCALENDAR, MKCALENDAR) \
231   XX(31, LINK, LINK) \
232   XX(32, UNLINK, UNLINK) \
233   XX(33, SOURCE, SOURCE) \
234
235
236 #define RTSP_METHOD_MAP(XX) \
237   XX(1, GET, GET) \
238   XX(3, POST, POST) \
239   XX(6, OPTIONS, OPTIONS) \
240   XX(35, DESCRIBE, DESCRIBE) \
241   XX(36, ANNOUNCE, ANNOUNCE) \
242   XX(37, SETUP, SETUP) \
243   XX(38, PLAY, PLAY) \
244   XX(39, PAUSE, PAUSE) \
245   XX(40, TEARDOWN, TEARDOWN) \
246   XX(41, GET_PARAMETER, GET_PARAMETER) \
247   XX(42, SET_PARAMETER, SET_PARAMETER) \
248   XX(43, REDIRECT, REDIRECT) \
249   XX(44, RECORD, RECORD) \
250   XX(45, FLUSH, FLUSH) \
251
252
253 #define HTTP_ALL_METHOD_MAP(XX) \
254   XX(0, DELETE, DELETE) \
255   XX(1, GET, GET) \
256   XX(2, HEAD, HEAD) \
257   XX(3, POST, POST) \
258   XX(4, PUT, PUT) \
259   XX(5, CONNECT, CONNECT) \
260   XX(6, OPTIONS, OPTIONS) \
261   XX(7, TRACE, TRACE) \
262   XX(8, COPY, COPY) \
263   XX(9, LOCK, LOCK) \
264   XX(10, MKCOL, MKCOL) \
265   XX(11, MOVE, MOVE) \
266   XX(12, PROPFIND, PROPFIND) \
267   XX(13, PROPPATCH, PROPPATCH) \
268   XX(14, SEARCH, SEARCH) \
269   XX(15, UNLOCK, UNLOCK) \
270   XX(16, BIND, BIND) \
271   XX(17, REBIND, REBIND) \
272   XX(18, UNBIND, UNBIND) \
273   XX(19, ACL, ACL) \
274   XX(20, REPORT, REPORT) \
275   XX(21, MKACTIVITY, MKACTIVITY) \
276   XX(22, CHECKOUT, CHECKOUT) \
277   XX(23, MERGE, MERGE) \
278   XX(24, MSEARCH, M-SEARCH) \
279   XX(25, NOTIFY, NOTIFY) \
280   XX(26, SUBSCRIBE, SUBSCRIBE) \
281   XX(27, UNSUBSCRIBE, UNSUBSCRIBE) \
282   XX(28, PATCH, PATCH) \
283   XX(29, PURGE, PURGE) \
284   XX(30, MKCALENDAR, MKCALENDAR) \
285   XX(31, LINK, LINK) \
286   XX(32, UNLINK, UNLINK) \
287   XX(33, SOURCE, SOURCE) \
288   XX(34, PRI, PRI) \
289   XX(35, DESCRIBE, DESCRIBE) \
290   XX(36, ANNOUNCE, ANNOUNCE) \
291   XX(37, SETUP, SETUP) \
292   XX(38, PLAY, PLAY) \
293   XX(39, PAUSE, PAUSE) \
294   XX(40, TEARDOWN, TEARDOWN) \
295   XX(41, GET_PARAMETER, GET_PARAMETER) \
296   XX(42, SET_PARAMETER, SET_PARAMETER) \
297   XX(43, REDIRECT, REDIRECT) \
298   XX(44, RECORD, RECORD) \
299   XX(45, FLUSH, FLUSH) \
300
301
302 #ifdef __cplusplus
303 }  /* extern "C" */
304 #endif
305 #endif  /* LLLLHTTP_C_HEADERS_ */
306
307 #ifndef INCLUDE_LLHTTP_API_H_
308 #define INCLUDE_LLHTTP_API_H_
309 #ifdef __cplusplus
310 extern "C" {
311 #endif
312 #include <stddef.h>
313
314 #if defined(__wasm__)
315 #define LLHTTP_EXPORT __attribute__((visibility("default")))
316 #else
317 #define LLHTTP_EXPORT
318 #endif
319
320 typedef llhttp__internal_t llhttp_t;
321 typedef struct llhttp_settings_s llhttp_settings_t;
322
323 typedef int (*llhttp_data_cb)(llhttp_t*, const char *at, size_t length);
324 typedef int (*llhttp_cb)(llhttp_t*);
325
326 struct llhttp_settings_s {
327   /* Possible return values 0, -1, `HPE_PAUSED` */
328   llhttp_cb      on_message_begin;
329
330   /* Possible return values 0, -1, HPE_USER */
331   llhttp_data_cb on_url;
332   llhttp_data_cb on_status;
333   llhttp_data_cb on_header_field;
334   llhttp_data_cb on_header_value;
335
336   /* Possible return values:
337    * 0  - Proceed normally
338    * 1  - Assume that request/response has no body, and proceed to parsing the
339    *      next message
340    * 2  - Assume absence of body (as above) and make `llhttp_execute()` return
341    *      `HPE_PAUSED_UPGRADE`
342    * -1 - Error
343    * `HPE_PAUSED`
344    */
345   llhttp_cb      on_headers_complete;
346
347   /* Possible return values 0, -1, HPE_USER */
348   llhttp_data_cb on_body;
349
350   /* Possible return values 0, -1, `HPE_PAUSED` */
351   llhttp_cb      on_message_complete;
352
353   /* When on_chunk_header is called, the current chunk length is stored
354    * in parser->content_length.
355    * Possible return values 0, -1, `HPE_PAUSED`
356    */
357   llhttp_cb      on_chunk_header;
358   llhttp_cb      on_chunk_complete;
359
360   /* Information-only callbacks, return value is ignored */
361   llhttp_cb      on_url_complete;
362   llhttp_cb      on_status_complete;
363   llhttp_cb      on_header_field_complete;
364   llhttp_cb      on_header_value_complete;
365 };
366
367 /* Initialize the parser with specific type and user settings.
368  *
369  * NOTE: lifetime of `settings` has to be at least the same as the lifetime of
370  * the `parser` here. In practice, `settings` has to be either a static
371  * variable or be allocated with `malloc`, `new`, etc.
372  */
373 LLHTTP_EXPORT
374 void llhttp_init(llhttp_t* parser, llhttp_type_t type,
375                  const llhttp_settings_t* settings);
376
377 #if defined(__wasm__)
378
379 LLHTTP_EXPORT
380 llhttp_t* llhttp_alloc(llhttp_type_t type);
381
382 LLHTTP_EXPORT
383 void llhttp_free(llhttp_t* parser);
384
385 LLHTTP_EXPORT
386 uint8_t llhttp_get_type(llhttp_t* parser);
387
388 LLHTTP_EXPORT
389 uint8_t llhttp_get_http_major(llhttp_t* parser);
390
391 LLHTTP_EXPORT
392 uint8_t llhttp_get_http_minor(llhttp_t* parser);
393
394 LLHTTP_EXPORT
395 uint8_t llhttp_get_method(llhttp_t* parser);
396
397 LLHTTP_EXPORT
398 int llhttp_get_status_code(llhttp_t* parser);
399
400 LLHTTP_EXPORT
401 uint8_t llhttp_get_upgrade(llhttp_t* parser);
402
403 #endif  // defined(__wasm__)
404
405 /* Reset an already initialized parser back to the start state, preserving the
406  * existing parser type, callback settings, user data, and lenient flags.
407  */
408 LLHTTP_EXPORT
409 void llhttp_reset(llhttp_t* parser);
410
411 /* Initialize the settings object */
412 LLHTTP_EXPORT
413 void llhttp_settings_init(llhttp_settings_t* settings);
414
415 /* Parse full or partial request/response, invoking user callbacks along the
416  * way.
417  *
418  * If any of `llhttp_data_cb` returns errno not equal to `HPE_OK` - the parsing
419  * interrupts, and such errno is returned from `llhttp_execute()`. If
420  * `HPE_PAUSED` was used as a errno, the execution can be resumed with
421  * `llhttp_resume()` call.
422  *
423  * In a special case of CONNECT/Upgrade request/response `HPE_PAUSED_UPGRADE`
424  * is returned after fully parsing the request/response. If the user wishes to
425  * continue parsing, they need to invoke `llhttp_resume_after_upgrade()`.
426  *
427  * NOTE: if this function ever returns a non-pause type error, it will continue
428  * to return the same error upon each successive call up until `llhttp_init()`
429  * is called.
430  */
431 LLHTTP_EXPORT
432 llhttp_errno_t llhttp_execute(llhttp_t* parser, const char* data, size_t len);
433
434 /* This method should be called when the other side has no further bytes to
435  * send (e.g. shutdown of readable side of the TCP connection.)
436  *
437  * Requests without `Content-Length` and other messages might require treating
438  * all incoming bytes as the part of the body, up to the last byte of the
439  * connection. This method will invoke `on_message_complete()` callback if the
440  * request was terminated safely. Otherwise a error code would be returned.
441  */
442 LLHTTP_EXPORT
443 llhttp_errno_t llhttp_finish(llhttp_t* parser);
444
445 /* Returns `1` if the incoming message is parsed until the last byte, and has
446  * to be completed by calling `llhttp_finish()` on EOF
447  */
448 LLHTTP_EXPORT
449 int llhttp_message_needs_eof(const llhttp_t* parser);
450
451 /* Returns `1` if there might be any other messages following the last that was
452  * successfully parsed.
453  */
454 LLHTTP_EXPORT
455 int llhttp_should_keep_alive(const llhttp_t* parser);
456
457 /* Make further calls of `llhttp_execute()` return `HPE_PAUSED` and set
458  * appropriate error reason.
459  *
460  * Important: do not call this from user callbacks! User callbacks must return
461  * `HPE_PAUSED` if pausing is required.
462  */
463 LLHTTP_EXPORT
464 void llhttp_pause(llhttp_t* parser);
465
466 /* Might be called to resume the execution after the pause in user's callback.
467  * See `llhttp_execute()` above for details.
468  *
469  * Call this only if `llhttp_execute()` returns `HPE_PAUSED`.
470  */
471 LLHTTP_EXPORT
472 void llhttp_resume(llhttp_t* parser);
473
474 /* Might be called to resume the execution after the pause in user's callback.
475  * See `llhttp_execute()` above for details.
476  *
477  * Call this only if `llhttp_execute()` returns `HPE_PAUSED_UPGRADE`
478  */
479 LLHTTP_EXPORT
480 void llhttp_resume_after_upgrade(llhttp_t* parser);
481
482 /* Returns the latest return error */
483 LLHTTP_EXPORT
484 llhttp_errno_t llhttp_get_errno(const llhttp_t* parser);
485
486 /* Returns the verbal explanation of the latest returned error.
487  *
488  * Note: User callback should set error reason when returning the error. See
489  * `llhttp_set_error_reason()` for details.
490  */
491 LLHTTP_EXPORT
492 const char* llhttp_get_error_reason(const llhttp_t* parser);
493
494 /* Assign verbal description to the returned error. Must be called in user
495  * callbacks right before returning the errno.
496  *
497  * Note: `HPE_USER` error code might be useful in user callbacks.
498  */
499 LLHTTP_EXPORT
500 void llhttp_set_error_reason(llhttp_t* parser, const char* reason);
501
502 /* Returns the pointer to the last parsed byte before the returned error. The
503  * pointer is relative to the `data` argument of `llhttp_execute()`.
504  *
505  * Note: this method might be useful for counting the number of parsed bytes.
506  */
507 LLHTTP_EXPORT
508 const char* llhttp_get_error_pos(const llhttp_t* parser);
509
510 /* Returns textual name of error code */
511 LLHTTP_EXPORT
512 const char* llhttp_errno_name(llhttp_errno_t err);
513
514 /* Returns textual name of HTTP method */
515 LLHTTP_EXPORT
516 const char* llhttp_method_name(llhttp_method_t method);
517
518
519 /* Enables/disables lenient header value parsing (disabled by default).
520  *
521  * Lenient parsing disables header value token checks, extending llhttp's
522  * protocol support to highly non-compliant clients/server. No
523  * `HPE_INVALID_HEADER_TOKEN` will be raised for incorrect header values when
524  * lenient parsing is "on".
525  *
526  * **(USE AT YOUR OWN RISK)**
527  */
528 LLHTTP_EXPORT
529 void llhttp_set_lenient_headers(llhttp_t* parser, int enabled);
530
531
532 /* Enables/disables lenient handling of conflicting `Transfer-Encoding` and
533  * `Content-Length` headers (disabled by default).
534  *
535  * Normally `llhttp` would error when `Transfer-Encoding` is present in
536  * conjunction with `Content-Length`. This error is important to prevent HTTP
537  * request smuggling, but may be less desirable for small number of cases
538  * involving legacy servers.
539  *
540  * **(USE AT YOUR OWN RISK)**
541  */
542 LLHTTP_EXPORT
543 void llhttp_set_lenient_chunked_length(llhttp_t* parser, int enabled);
544
545
546 /* Enables/disables lenient handling of `Connection: close` and HTTP/1.0
547  * requests responses.
548  *
549  * Normally `llhttp` would error on (in strict mode) or discard (in loose mode)
550  * the HTTP request/response after the request/response with `Connection: close`
551  * and `Content-Length`. This is important to prevent cache poisoning attacks,
552  * but might interact badly with outdated and insecure clients. With this flag
553  * the extra request/response will be parsed normally.
554  *
555  * **(USE AT YOUR OWN RISK)**
556  */
557 void llhttp_set_lenient_keep_alive(llhttp_t* parser, int enabled);
558
559 #ifdef __cplusplus
560 }  /* extern "C" */
561 #endif
562 #endif  /* INCLUDE_LLHTTP_API_H_ */
563
564 #endif  /* INCLUDE_LLHTTP_H_ */