1 #ifndef INCLUDE_LLHTTP_H_
2 #define INCLUDE_LLHTTP_H_
4 #define LLHTTP_VERSION_MAJOR 6
5 #define LLHTTP_VERSION_MINOR 0
6 #define LLHTTP_VERSION_PATCH 2
8 #ifndef LLHTTP_STRICT_MODE
9 # define LLHTTP_STRICT_MODE 0
12 #ifndef INCLUDE_LLHTTP_ITSELF_H_
13 #define INCLUDE_LLHTTP_ITSELF_H_
20 typedef struct llhttp__internal_s llhttp__internal_t;
21 struct llhttp__internal_s {
27 const char* error_pos;
30 uint64_t content_length;
36 uint8_t lenient_flags;
44 int llhttp__internal_init(llhttp__internal_t* s);
45 int llhttp__internal_execute(llhttp__internal_t* s, const char* p, const char* endp);
50 #endif /* INCLUDE_LLHTTP_ITSELF_H_ */
52 #ifndef LLLLHTTP_C_HEADERS_
53 #define LLLLHTTP_C_HEADERS_
63 HPE_UNEXPECTED_CONTENT_LENGTH = 4,
64 HPE_CLOSED_CONNECTION = 5,
65 HPE_INVALID_METHOD = 6,
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,
81 HPE_PAUSED_UPGRADE = 22,
82 HPE_PAUSED_H2_UPGRADE = 23,
85 typedef enum llhttp_errno llhttp_errno_t;
88 F_CONNECTION_KEEP_ALIVE = 0x1,
89 F_CONNECTION_CLOSE = 0x2,
90 F_CONNECTION_UPGRADE = 0x4,
93 F_CONTENT_LENGTH = 0x20,
96 F_TRANSFER_ENCODING = 0x200
98 typedef enum llhttp_flags llhttp_flags_t;
100 enum llhttp_lenient_flags {
101 LENIENT_HEADERS = 0x1,
102 LENIENT_CHUNKED_LENGTH = 0x2,
103 LENIENT_KEEP_ALIVE = 0x4
105 typedef enum llhttp_lenient_flags llhttp_lenient_flags_t;
112 typedef enum llhttp_type llhttp_type_t;
115 HTTP_FINISH_SAFE = 0,
116 HTTP_FINISH_SAFE_WITH_CB = 1,
117 HTTP_FINISH_UNSAFE = 2
119 typedef enum llhttp_finish llhttp_finish_t;
143 HTTP_MKACTIVITY = 21,
149 HTTP_UNSUBSCRIBE = 27,
152 HTTP_MKCALENDAR = 30,
163 HTTP_GET_PARAMETER = 41,
164 HTTP_SET_PARAMETER = 42,
169 typedef enum llhttp_method llhttp_method_t;
171 #define HTTP_ERRNO_MAP(XX) \
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) \
199 #define HTTP_METHOD_MAP(XX) \
200 XX(0, DELETE, DELETE) \
205 XX(5, CONNECT, CONNECT) \
206 XX(6, OPTIONS, OPTIONS) \
207 XX(7, TRACE, TRACE) \
210 XX(10, MKCOL, MKCOL) \
212 XX(12, PROPFIND, PROPFIND) \
213 XX(13, PROPPATCH, PROPPATCH) \
214 XX(14, SEARCH, SEARCH) \
215 XX(15, UNLOCK, UNLOCK) \
217 XX(17, REBIND, REBIND) \
218 XX(18, UNBIND, UNBIND) \
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) \
232 XX(32, UNLINK, UNLINK) \
233 XX(33, SOURCE, SOURCE) \
236 #define RTSP_METHOD_MAP(XX) \
239 XX(6, OPTIONS, OPTIONS) \
240 XX(35, DESCRIBE, DESCRIBE) \
241 XX(36, ANNOUNCE, ANNOUNCE) \
242 XX(37, SETUP, SETUP) \
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) \
253 #define HTTP_ALL_METHOD_MAP(XX) \
254 XX(0, DELETE, DELETE) \
259 XX(5, CONNECT, CONNECT) \
260 XX(6, OPTIONS, OPTIONS) \
261 XX(7, TRACE, TRACE) \
264 XX(10, MKCOL, MKCOL) \
266 XX(12, PROPFIND, PROPFIND) \
267 XX(13, PROPPATCH, PROPPATCH) \
268 XX(14, SEARCH, SEARCH) \
269 XX(15, UNLOCK, UNLOCK) \
271 XX(17, REBIND, REBIND) \
272 XX(18, UNBIND, UNBIND) \
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) \
286 XX(32, UNLINK, UNLINK) \
287 XX(33, SOURCE, SOURCE) \
289 XX(35, DESCRIBE, DESCRIBE) \
290 XX(36, ANNOUNCE, ANNOUNCE) \
291 XX(37, SETUP, SETUP) \
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) \
305 #endif /* LLLLHTTP_C_HEADERS_ */
307 #ifndef INCLUDE_LLHTTP_API_H_
308 #define INCLUDE_LLHTTP_API_H_
314 #if defined(__wasm__)
315 #define LLHTTP_EXPORT __attribute__((visibility("default")))
317 #define LLHTTP_EXPORT
320 typedef llhttp__internal_t llhttp_t;
321 typedef struct llhttp_settings_s llhttp_settings_t;
323 typedef int (*llhttp_data_cb)(llhttp_t*, const char *at, size_t length);
324 typedef int (*llhttp_cb)(llhttp_t*);
326 struct llhttp_settings_s {
327 /* Possible return values 0, -1, `HPE_PAUSED` */
328 llhttp_cb on_message_begin;
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;
336 /* Possible return values:
337 * 0 - Proceed normally
338 * 1 - Assume that request/response has no body, and proceed to parsing the
340 * 2 - Assume absence of body (as above) and make `llhttp_execute()` return
341 * `HPE_PAUSED_UPGRADE`
345 llhttp_cb on_headers_complete;
347 /* Possible return values 0, -1, HPE_USER */
348 llhttp_data_cb on_body;
350 /* Possible return values 0, -1, `HPE_PAUSED` */
351 llhttp_cb on_message_complete;
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`
357 llhttp_cb on_chunk_header;
358 llhttp_cb on_chunk_complete;
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;
367 /* Initialize the parser with specific type and user settings.
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.
374 void llhttp_init(llhttp_t* parser, llhttp_type_t type,
375 const llhttp_settings_t* settings);
377 #if defined(__wasm__)
380 llhttp_t* llhttp_alloc(llhttp_type_t type);
383 void llhttp_free(llhttp_t* parser);
386 uint8_t llhttp_get_type(llhttp_t* parser);
389 uint8_t llhttp_get_http_major(llhttp_t* parser);
392 uint8_t llhttp_get_http_minor(llhttp_t* parser);
395 uint8_t llhttp_get_method(llhttp_t* parser);
398 int llhttp_get_status_code(llhttp_t* parser);
401 uint8_t llhttp_get_upgrade(llhttp_t* parser);
403 #endif // defined(__wasm__)
405 /* Reset an already initialized parser back to the start state, preserving the
406 * existing parser type, callback settings, user data, and lenient flags.
409 void llhttp_reset(llhttp_t* parser);
411 /* Initialize the settings object */
413 void llhttp_settings_init(llhttp_settings_t* settings);
415 /* Parse full or partial request/response, invoking user callbacks along the
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.
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()`.
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()`
432 llhttp_errno_t llhttp_execute(llhttp_t* parser, const char* data, size_t len);
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.)
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.
443 llhttp_errno_t llhttp_finish(llhttp_t* parser);
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
449 int llhttp_message_needs_eof(const llhttp_t* parser);
451 /* Returns `1` if there might be any other messages following the last that was
452 * successfully parsed.
455 int llhttp_should_keep_alive(const llhttp_t* parser);
457 /* Make further calls of `llhttp_execute()` return `HPE_PAUSED` and set
458 * appropriate error reason.
460 * Important: do not call this from user callbacks! User callbacks must return
461 * `HPE_PAUSED` if pausing is required.
464 void llhttp_pause(llhttp_t* parser);
466 /* Might be called to resume the execution after the pause in user's callback.
467 * See `llhttp_execute()` above for details.
469 * Call this only if `llhttp_execute()` returns `HPE_PAUSED`.
472 void llhttp_resume(llhttp_t* parser);
474 /* Might be called to resume the execution after the pause in user's callback.
475 * See `llhttp_execute()` above for details.
477 * Call this only if `llhttp_execute()` returns `HPE_PAUSED_UPGRADE`
480 void llhttp_resume_after_upgrade(llhttp_t* parser);
482 /* Returns the latest return error */
484 llhttp_errno_t llhttp_get_errno(const llhttp_t* parser);
486 /* Returns the verbal explanation of the latest returned error.
488 * Note: User callback should set error reason when returning the error. See
489 * `llhttp_set_error_reason()` for details.
492 const char* llhttp_get_error_reason(const llhttp_t* parser);
494 /* Assign verbal description to the returned error. Must be called in user
495 * callbacks right before returning the errno.
497 * Note: `HPE_USER` error code might be useful in user callbacks.
500 void llhttp_set_error_reason(llhttp_t* parser, const char* reason);
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()`.
505 * Note: this method might be useful for counting the number of parsed bytes.
508 const char* llhttp_get_error_pos(const llhttp_t* parser);
510 /* Returns textual name of error code */
512 const char* llhttp_errno_name(llhttp_errno_t err);
514 /* Returns textual name of HTTP method */
516 const char* llhttp_method_name(llhttp_method_t method);
519 /* Enables/disables lenient header value parsing (disabled by default).
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".
526 * **(USE AT YOUR OWN RISK)**
529 void llhttp_set_lenient_headers(llhttp_t* parser, int enabled);
532 /* Enables/disables lenient handling of conflicting `Transfer-Encoding` and
533 * `Content-Length` headers (disabled by default).
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.
540 * **(USE AT YOUR OWN RISK)**
543 void llhttp_set_lenient_chunked_length(llhttp_t* parser, int enabled);
546 /* Enables/disables lenient handling of `Connection: close` and HTTP/1.0
547 * requests responses.
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.
555 * **(USE AT YOUR OWN RISK)**
557 void llhttp_set_lenient_keep_alive(llhttp_t* parser, int enabled);
562 #endif /* INCLUDE_LLHTTP_API_H_ */
564 #endif /* INCLUDE_LLHTTP_H_ */