1 /* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25 /* minimal space for typical headers and CSP stuff */ 26 27 #define LWS_RECOMMENDED_MIN_HEADER_SPACE 2048 28 29 /*! \defgroup http HTTP 30 31 Modules related to handling HTTP 32 */ 33 //@{ 34 35 /*! \defgroup httpft HTTP File transfer 36 * \ingroup http 37 38 APIs for sending local files in response to HTTP requests 39 */ 40 //@{ 41 42 /** 43 * lws_get_mimetype() - Determine mimetype to use from filename 44 * 45 * \param file: filename 46 * \param m: NULL, or mount context 47 * 48 * This uses a canned list of known filetypes first, if no match and m is 49 * non-NULL, then tries a list of per-mount file suffix to mimtype mappings. 50 * 51 * Returns either NULL or a pointer to the mimetype matching the file. 52 */ 53 LWS_VISIBLE LWS_EXTERN const char * 54 lws_get_mimetype(const char *file, const struct lws_http_mount *m); 55 56 /** 57 * lws_serve_http_file() - Send a file back to the client using http 58 * \param wsi: Websocket instance (available from user callback) 59 * \param file: The file to issue over http 60 * \param content_type: The http content type, eg, text/html 61 * \param other_headers: NULL or pointer to header string 62 * \param other_headers_len: length of the other headers if non-NULL 63 * 64 * This function is intended to be called from the callback in response 65 * to http requests from the client. It allows the callback to issue 66 * local files down the http link in a single step. 67 * 68 * Returning <0 indicates error and the wsi should be closed. Returning 69 * >0 indicates the file was completely sent and 70 * lws_http_transaction_completed() called on the wsi (and close if != 0) 71 * ==0 indicates the file transfer is started and needs more service later, 72 * the wsi should be left alone. 73 */ 74 LWS_VISIBLE LWS_EXTERN int 75 lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type, 76 const char *other_headers, int other_headers_len); 77 78 LWS_VISIBLE LWS_EXTERN int 79 lws_serve_http_file_fragment(struct lws *wsi); 80 //@} 81 82 83 enum http_status { 84 HTTP_STATUS_CONTINUE = 100, 85 86 HTTP_STATUS_OK = 200, 87 HTTP_STATUS_NO_CONTENT = 204, 88 HTTP_STATUS_PARTIAL_CONTENT = 206, 89 90 HTTP_STATUS_MOVED_PERMANENTLY = 301, 91 HTTP_STATUS_FOUND = 302, 92 HTTP_STATUS_SEE_OTHER = 303, 93 HTTP_STATUS_NOT_MODIFIED = 304, 94 95 HTTP_STATUS_BAD_REQUEST = 400, 96 HTTP_STATUS_UNAUTHORIZED, 97 HTTP_STATUS_PAYMENT_REQUIRED, 98 HTTP_STATUS_FORBIDDEN, 99 HTTP_STATUS_NOT_FOUND, 100 HTTP_STATUS_METHOD_NOT_ALLOWED, 101 HTTP_STATUS_NOT_ACCEPTABLE, 102 HTTP_STATUS_PROXY_AUTH_REQUIRED, 103 HTTP_STATUS_REQUEST_TIMEOUT, 104 HTTP_STATUS_CONFLICT, 105 HTTP_STATUS_GONE, 106 HTTP_STATUS_LENGTH_REQUIRED, 107 HTTP_STATUS_PRECONDITION_FAILED, 108 HTTP_STATUS_REQ_ENTITY_TOO_LARGE, 109 HTTP_STATUS_REQ_URI_TOO_LONG, 110 HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE, 111 HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE, 112 HTTP_STATUS_EXPECTATION_FAILED, 113 114 HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, 115 HTTP_STATUS_NOT_IMPLEMENTED, 116 HTTP_STATUS_BAD_GATEWAY, 117 HTTP_STATUS_SERVICE_UNAVAILABLE, 118 HTTP_STATUS_GATEWAY_TIMEOUT, 119 HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED, 120 }; 121 /*! \defgroup html-chunked-substitution HTML Chunked Substitution 122 * \ingroup http 123 * 124 * ##HTML chunked Substitution 125 * 126 * APIs for receiving chunks of text, replacing a set of variable names via 127 * a callback, and then prepending and appending HTML chunked encoding 128 * headers. 129 */ 130 //@{ 131 132 struct lws_process_html_args { 133 char *p; /**< pointer to the buffer containing the data */ 134 int len; /**< length of the original data at p */ 135 int max_len; /**< maximum length we can grow the data to */ 136 int final; /**< set if this is the last chunk of the file */ 137 int chunked; /**< 0 == unchunked, 1 == produce chunk headers 138 (incompatible with HTTP/2) */ 139 }; 140 141 typedef const char *(*lws_process_html_state_cb)(void *data, int index); 142 143 struct lws_process_html_state { 144 char *start; /**< pointer to start of match */ 145 char swallow[16]; /**< matched character buffer */ 146 int pos; /**< position in match */ 147 void *data; /**< opaque pointer */ 148 const char * const *vars; /**< list of variable names */ 149 int count_vars; /**< count of variable names */ 150 151 lws_process_html_state_cb replace; 152 /**< called on match to perform substitution */ 153 }; 154 155 /*! lws_chunked_html_process() - generic chunked substitution 156 * \param args: buffer to process using chunked encoding 157 * \param s: current processing state 158 */ 159 LWS_VISIBLE LWS_EXTERN int 160 lws_chunked_html_process(struct lws_process_html_args *args, 161 struct lws_process_html_state *s); 162 //@} 163 164 /** \defgroup HTTP-headers-read HTTP headers: read 165 * \ingroup http 166 * 167 * ##HTTP header releated functions 168 * 169 * In lws the client http headers are temporarily stored in a pool, only for the 170 * duration of the http part of the handshake. It's because in most cases, 171 * the header content is ignored for the whole rest of the connection lifetime 172 * and would then just be taking up space needlessly. 173 * 174 * During LWS_CALLBACK_HTTP when the URI path is delivered is the last time 175 * the http headers are still allocated, you can use these apis then to 176 * look at and copy out interesting header content (cookies, etc) 177 * 178 * Notice that the header total length reported does not include a terminating 179 * '\0', however you must allocate for it when using the _copy apis. So the 180 * length reported for a header containing "123" is 3, but you must provide 181 * a buffer of length 4 so that "123\0" may be copied into it, or the copy 182 * will fail with a nonzero return code. 183 * 184 * In the special case of URL arguments, like ?x=1&y=2, the arguments are 185 * stored in a token named for the method, eg, WSI_TOKEN_GET_URI if it 186 * was a GET or WSI_TOKEN_POST_URI if POST. You can check the total 187 * length to confirm the method. 188 * 189 * For URL arguments, each argument is stored urldecoded in a "fragment", so 190 * you can use the fragment-aware api lws_hdr_copy_fragment() to access each 191 * argument in turn: the fragments contain urldecoded strings like x=1 or y=2. 192 * 193 * As a convenience, lws has an api that will find the fragment with a 194 * given name= part, lws_get_urlarg_by_name(). 195 */ 196 ///@{ 197 198 /** struct lws_tokens 199 * you need these to look at headers that have been parsed if using the 200 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum 201 * list below is absent, .token = NULL and len = 0. Otherwise .token 202 * points to .len chars containing that header content. 203 */ 204 struct lws_tokens { 205 unsigned char *token; /**< pointer to start of the token */ 206 int len; /**< length of the token's value */ 207 }; 208 209 /* enum lws_token_indexes 210 * these have to be kept in sync with lextable.h / minilex.c 211 * 212 * NOTE: These public enums are part of the abi. If you want to add one, 213 * add it at where specified so existing users are unaffected. 214 */ 215 enum lws_token_indexes { 216 WSI_TOKEN_GET_URI, /* 0 */ 217 WSI_TOKEN_POST_URI, 218 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL) 219 WSI_TOKEN_OPTIONS_URI, 220 #endif 221 WSI_TOKEN_HOST, 222 WSI_TOKEN_CONNECTION, 223 WSI_TOKEN_UPGRADE, /* 5 */ 224 WSI_TOKEN_ORIGIN, 225 #if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL) 226 WSI_TOKEN_DRAFT, 227 #endif 228 WSI_TOKEN_CHALLENGE, 229 #if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL) 230 WSI_TOKEN_EXTENSIONS, 231 WSI_TOKEN_KEY1, /* 10 */ 232 WSI_TOKEN_KEY2, 233 WSI_TOKEN_PROTOCOL, 234 WSI_TOKEN_ACCEPT, 235 WSI_TOKEN_NONCE, 236 #endif 237 WSI_TOKEN_HTTP, 238 #if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 239 WSI_TOKEN_HTTP2_SETTINGS, /* 16 */ 240 #endif 241 WSI_TOKEN_HTTP_ACCEPT, 242 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL) 243 WSI_TOKEN_HTTP_AC_REQUEST_HEADERS, 244 #endif 245 WSI_TOKEN_HTTP_IF_MODIFIED_SINCE, 246 WSI_TOKEN_HTTP_IF_NONE_MATCH, /* 20 */ 247 WSI_TOKEN_HTTP_ACCEPT_ENCODING, 248 WSI_TOKEN_HTTP_ACCEPT_LANGUAGE, 249 WSI_TOKEN_HTTP_PRAGMA, 250 WSI_TOKEN_HTTP_CACHE_CONTROL, 251 WSI_TOKEN_HTTP_AUTHORIZATION, 252 WSI_TOKEN_HTTP_COOKIE, 253 WSI_TOKEN_HTTP_CONTENT_LENGTH, /* 27 */ 254 WSI_TOKEN_HTTP_CONTENT_TYPE, 255 WSI_TOKEN_HTTP_DATE, 256 WSI_TOKEN_HTTP_RANGE, 257 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 258 WSI_TOKEN_HTTP_REFERER, 259 #endif 260 #if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL) 261 WSI_TOKEN_KEY, 262 WSI_TOKEN_VERSION, 263 WSI_TOKEN_SWORIGIN, 264 #endif 265 #if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 266 WSI_TOKEN_HTTP_COLON_AUTHORITY, 267 WSI_TOKEN_HTTP_COLON_METHOD, 268 WSI_TOKEN_HTTP_COLON_PATH, 269 WSI_TOKEN_HTTP_COLON_SCHEME, 270 WSI_TOKEN_HTTP_COLON_STATUS, 271 #endif 272 273 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 274 WSI_TOKEN_HTTP_ACCEPT_CHARSET, 275 #endif 276 WSI_TOKEN_HTTP_ACCEPT_RANGES, 277 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 278 WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN, 279 #endif 280 WSI_TOKEN_HTTP_AGE, 281 WSI_TOKEN_HTTP_ALLOW, 282 WSI_TOKEN_HTTP_CONTENT_DISPOSITION, 283 WSI_TOKEN_HTTP_CONTENT_ENCODING, 284 WSI_TOKEN_HTTP_CONTENT_LANGUAGE, 285 WSI_TOKEN_HTTP_CONTENT_LOCATION, 286 WSI_TOKEN_HTTP_CONTENT_RANGE, 287 WSI_TOKEN_HTTP_ETAG, 288 WSI_TOKEN_HTTP_EXPECT, 289 WSI_TOKEN_HTTP_EXPIRES, 290 WSI_TOKEN_HTTP_FROM, 291 WSI_TOKEN_HTTP_IF_MATCH, 292 WSI_TOKEN_HTTP_IF_RANGE, 293 WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE, 294 WSI_TOKEN_HTTP_LAST_MODIFIED, 295 WSI_TOKEN_HTTP_LINK, 296 WSI_TOKEN_HTTP_LOCATION, 297 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 298 WSI_TOKEN_HTTP_MAX_FORWARDS, 299 WSI_TOKEN_HTTP_PROXY_AUTHENTICATE, 300 WSI_TOKEN_HTTP_PROXY_AUTHORIZATION, 301 #endif 302 WSI_TOKEN_HTTP_REFRESH, 303 WSI_TOKEN_HTTP_RETRY_AFTER, 304 WSI_TOKEN_HTTP_SERVER, 305 WSI_TOKEN_HTTP_SET_COOKIE, 306 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 307 WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY, 308 #endif 309 WSI_TOKEN_HTTP_TRANSFER_ENCODING, 310 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 311 WSI_TOKEN_HTTP_USER_AGENT, 312 WSI_TOKEN_HTTP_VARY, 313 WSI_TOKEN_HTTP_VIA, 314 WSI_TOKEN_HTTP_WWW_AUTHENTICATE, 315 #endif 316 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL) 317 WSI_TOKEN_PATCH_URI, 318 WSI_TOKEN_PUT_URI, 319 WSI_TOKEN_DELETE_URI, 320 #endif 321 322 WSI_TOKEN_HTTP_URI_ARGS, 323 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL) 324 WSI_TOKEN_PROXY, 325 WSI_TOKEN_HTTP_X_REAL_IP, 326 #endif 327 WSI_TOKEN_HTTP1_0, 328 WSI_TOKEN_X_FORWARDED_FOR, 329 WSI_TOKEN_CONNECT, 330 WSI_TOKEN_HEAD_URI, 331 #if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 332 WSI_TOKEN_TE, 333 WSI_TOKEN_REPLAY_NONCE, /* ACME */ 334 #endif 335 #if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL) 336 WSI_TOKEN_COLON_PROTOCOL, 337 #endif 338 WSI_TOKEN_X_AUTH_TOKEN, 339 WSI_TOKEN_DSS_SIGNATURE, 340 341 /****** add new things just above ---^ ******/ 342 343 /* use token storage to stash these internally, not for 344 * user use */ 345 346 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS, 347 _WSI_TOKEN_CLIENT_PEER_ADDRESS, 348 _WSI_TOKEN_CLIENT_URI, 349 _WSI_TOKEN_CLIENT_HOST, 350 _WSI_TOKEN_CLIENT_ORIGIN, 351 _WSI_TOKEN_CLIENT_METHOD, 352 _WSI_TOKEN_CLIENT_IFACE, 353 _WSI_TOKEN_CLIENT_ALPN, 354 355 /* always last real token index*/ 356 WSI_TOKEN_COUNT, 357 358 /* parser state additions, no storage associated */ 359 WSI_TOKEN_NAME_PART, 360 #if defined(LWS_WITH_CUSTOM_HEADERS) || defined(LWS_HTTP_HEADERS_ALL) 361 WSI_TOKEN_UNKNOWN_VALUE_PART, 362 #endif 363 WSI_TOKEN_SKIPPING, 364 WSI_TOKEN_SKIPPING_SAW_CR, 365 WSI_PARSING_COMPLETE, 366 WSI_INIT_TOKEN_MUXURL, 367 }; 368 369 struct lws_token_limits { 370 unsigned short token_limit[WSI_TOKEN_COUNT]; /**< max chars for this token */ 371 }; 372 373 enum lws_h2_settings { 374 H2SET_HEADER_TABLE_SIZE = 1, 375 H2SET_ENABLE_PUSH, 376 H2SET_MAX_CONCURRENT_STREAMS, 377 H2SET_INITIAL_WINDOW_SIZE, 378 H2SET_MAX_FRAME_SIZE, 379 H2SET_MAX_HEADER_LIST_SIZE, 380 H2SET_RESERVED7, 381 H2SET_ENABLE_CONNECT_PROTOCOL, /* defined in mcmanus-httpbis-h2-ws-02 */ 382 383 H2SET_COUNT /* always last */ 384 }; 385 386 /** 387 * lws_token_to_string() - returns a textual representation of a hdr token index 388 * 389 * \param token: token index 390 */ 391 LWS_VISIBLE LWS_EXTERN const unsigned char * 392 lws_token_to_string(enum lws_token_indexes token); 393 394 /** 395 * lws_hdr_total_length: report length of all fragments of a header totalled up 396 * The returned length does not include the space for a 397 * terminating '\0' 398 * 399 * \param wsi: websocket connection 400 * \param h: which header index we are interested in 401 */ 402 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 403 lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h); 404 405 /** 406 * lws_hdr_fragment_length: report length of a single fragment of a header 407 * The returned length does not include the space for a 408 * terminating '\0' 409 * 410 * \param wsi: websocket connection 411 * \param h: which header index we are interested in 412 * \param frag_idx: which fragment of h we want to get the length of 413 */ 414 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 415 lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, 416 int frag_idx); 417 418 /** 419 * lws_hdr_copy() - copy all fragments of the given header to a buffer 420 * The buffer length len must include space for an additional 421 * terminating '\0', or it will fail returning -1. 422 * 423 * \param wsi: websocket connection 424 * \param dest: destination buffer 425 * \param len: length of destination buffer 426 * \param h: which header index we are interested in 427 * 428 * copies the whole, aggregated header, even if it was delivered in 429 * several actual headers piece by piece. Returns -1 or length of the whole 430 * header. 431 */ 432 LWS_VISIBLE LWS_EXTERN int 433 lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h); 434 435 /** 436 * lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer 437 * The buffer length len must include space for an additional 438 * terminating '\0', or it will fail returning -1. 439 * If the requested fragment index is not present, it fails 440 * returning -1. 441 * 442 * \param wsi: websocket connection 443 * \param dest: destination buffer 444 * \param len: length of destination buffer 445 * \param h: which header index we are interested in 446 * \param frag_idx: which fragment of h we want to copy 447 * 448 * Normally this is only useful 449 * to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS 450 * fragment 0 will contain "x=1" and fragment 1 "y=2" 451 */ 452 LWS_VISIBLE LWS_EXTERN int 453 lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len, 454 enum lws_token_indexes h, int frag_idx); 455 456 /** 457 * lws_hdr_custom_length() - return length of a custom header 458 * 459 * \param wsi: websocket connection 460 * \param name: header string (including terminating :) 461 * \param nlen: length of name 462 * 463 * Lws knows about 100 common http headers, and parses them into indexes when 464 * it recognizes them. When it meets a header that it doesn't know, it stores 465 * the name and value directly, and you can look them up using 466 * lws_hdr_custom_length() and lws_hdr_custom_copy(). 467 * 468 * This api returns -1, or the length of the value part of the header if it 469 * exists. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to 470 * use this api. 471 */ 472 LWS_VISIBLE LWS_EXTERN int 473 lws_hdr_custom_length(struct lws *wsi, const char *name, int nlen); 474 475 /** 476 * lws_hdr_custom_copy() - copy value part of a custom header 477 * 478 * \param wsi: websocket connection 479 * \param dst: pointer to buffer to receive the copy 480 * \param len: number of bytes available at dst 481 * \param name: header string (including terminating :) 482 * \param nlen: length of name 483 * 484 * Lws knows about 100 common http headers, and parses them into indexes when 485 * it recognizes them. When it meets a header that it doesn't know, it stores 486 * the name and value directly, and you can look them up using 487 * lws_hdr_custom_length() and lws_hdr_custom_copy(). 488 * 489 * This api returns -1, or the length of the string it copied into dst if it 490 * was big enough to contain both the string and an extra terminating NUL. Lws 491 * must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api. 492 */ 493 LWS_VISIBLE LWS_EXTERN int 494 lws_hdr_custom_copy(struct lws *wsi, char *dst, int len, const char *name, 495 int nlen); 496 497 /** 498 * lws_get_urlarg_by_name_safe() - get copy and return length of y for x=y urlargs 499 * 500 * \param wsi: the connection to check 501 * \param name: the arg name, like "token" or "token=" 502 * \param buf: the buffer to receive the urlarg (including the name= part) 503 * \param len: the length of the buffer to receive the urlarg 504 * 505 * Returns -1 if not present, else the length of y in the urlarg name=y. If 506 * zero or greater, then buf contains a copy of the string y. Any = after the 507 * name match is trimmed off if the name does not end with = itself. 508 * 509 * This returns the explicit length and so can deal with binary blobs that are 510 * percent-encoded. It also makes sure buf has a NUL just after the valid 511 * length so it can work with NUL-based apis if you don't care about truncation. 512 * 513 * buf may have been written even when -1 is returned indicating no match. 514 * 515 * Use this in place of lws_get_urlarg_by_name() that does not return an 516 * explicit length. 517 * 518 * Use lws_get_urlarg_by_name_safe() instead of this, which returns the length. 519 */ 520 LWS_VISIBLE LWS_EXTERN int 521 lws_get_urlarg_by_name_safe(struct lws *wsi, const char *name, char *buf, int len); 522 523 /** 524 * lws_get_urlarg_by_name() - return pointer to arg value if present 525 * 526 * \param wsi: the connection to check 527 * \param name: the arg name, like "token=" 528 * \param buf: the buffer to receive the urlarg (including the name= part) 529 * \param len: the length of the buffer to receive the urlarg 530 * 531 * Returns NULL if not found or a pointer inside buf to just after the 532 * name= part. 533 * 534 * This assumed the argument can be represented with a NUL-terminated string. 535 * It can't correctly deal with binary values encoded with %XX, eg. %00 will 536 * be understood to terminate the string. 537 * 538 * Use lws_get_urlarg_by_name_safe() instead of this, which returns the length. 539 */ 540 LWS_VISIBLE LWS_EXTERN const char * 541 lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len) 542 /* LWS_WARN_DEPRECATED */; 543 ///@} 544 545 /*! \defgroup HTTP-headers-create HTTP headers: create 546 * 547 * ## HTTP headers: Create 548 * 549 * These apis allow you to create HTTP response headers in a way compatible with 550 * both HTTP/1.x and HTTP/2. 551 * 552 * They each append to a buffer taking care about the buffer end, which is 553 * passed in as a pointer. When data is written to the buffer, the current 554 * position p is updated accordingly. 555 * 556 * All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space 557 * and fail with nonzero return. 558 */ 559 ///@{ 560 561 #define LWSAHH_CODE_MASK ((1 << 16) - 1) 562 #define LWSAHH_FLAG_NO_SERVER_NAME (1 << 30) 563 564 /** 565 * lws_add_http_header_status() - add the HTTP response status code 566 * 567 * \param wsi: the connection to check 568 * \param code: an HTTP code like 200, 404 etc (see enum http_status) 569 * \param p: pointer to current position in buffer pointer 570 * \param end: pointer to end of buffer 571 * 572 * Adds the initial response code, so should be called first. 573 * 574 * Code may additionally take OR'd flags: 575 * 576 * LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time 577 */ 578 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 579 lws_add_http_header_status(struct lws *wsi, 580 unsigned int code, unsigned char **p, 581 unsigned char *end); 582 /** 583 * lws_add_http_header_by_name() - append named header and value 584 * 585 * \param wsi: the connection to check 586 * \param name: the hdr name, like "my-header:" 587 * \param value: the value after the = for this header 588 * \param length: the length of the value 589 * \param p: pointer to current position in buffer pointer 590 * \param end: pointer to end of buffer 591 * 592 * Appends name: value to the headers 593 */ 594 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 595 lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name, 596 const unsigned char *value, int length, 597 unsigned char **p, unsigned char *end); 598 /** 599 * lws_add_http_header_by_token() - append given header and value 600 * 601 * \param wsi: the connection to check 602 * \param token: the token index for the hdr 603 * \param value: the value after the = for this header 604 * \param length: the length of the value 605 * \param p: pointer to current position in buffer pointer 606 * \param end: pointer to end of buffer 607 * 608 * Appends name=value to the headers, but is able to take advantage of better 609 * HTTP/2 coding mechanisms where possible. 610 */ 611 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 612 lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token, 613 const unsigned char *value, int length, 614 unsigned char **p, unsigned char *end); 615 /** 616 * lws_add_http_header_content_length() - append content-length helper 617 * 618 * \param wsi: the connection to check 619 * \param content_length: the content length to use 620 * \param p: pointer to current position in buffer pointer 621 * \param end: pointer to end of buffer 622 * 623 * Appends content-length: content_length to the headers 624 */ 625 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 626 lws_add_http_header_content_length(struct lws *wsi, 627 lws_filepos_t content_length, 628 unsigned char **p, unsigned char *end); 629 /** 630 * lws_finalize_http_header() - terminate header block 631 * 632 * \param wsi: the connection to check 633 * \param p: pointer to current position in buffer pointer 634 * \param end: pointer to end of buffer 635 * 636 * Indicates no more headers will be added 637 */ 638 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 639 lws_finalize_http_header(struct lws *wsi, unsigned char **p, 640 unsigned char *end); 641 642 /** 643 * lws_finalize_write_http_header() - Helper finializing and writing http headers 644 * 645 * \param wsi: the connection to check 646 * \param start: pointer to the start of headers in the buffer, eg &buf[LWS_PRE] 647 * \param p: pointer to current position in buffer pointer 648 * \param end: pointer to end of buffer 649 * 650 * Terminates the headers correctly accoring to the protocol in use (h1 / h2) 651 * and writes the headers. Returns nonzero for error. 652 */ 653 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 654 lws_finalize_write_http_header(struct lws *wsi, unsigned char *start, 655 unsigned char **p, unsigned char *end); 656 657 #define LWS_ILLEGAL_HTTP_CONTENT_LEN ((lws_filepos_t)-1ll) 658 659 /** 660 * lws_add_http_common_headers() - Helper preparing common http headers 661 * 662 * \param wsi: the connection to check 663 * \param code: an HTTP code like 200, 404 etc (see enum http_status) 664 * \param content_type: the content type, like "text/html" 665 * \param content_len: the content length, in bytes 666 * \param p: pointer to current position in buffer pointer 667 * \param end: pointer to end of buffer 668 * 669 * Adds the initial response code, so should be called first. 670 * 671 * Code may additionally take OR'd flags: 672 * 673 * LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time 674 * 675 * This helper just calls public apis to simplify adding headers that are 676 * commonly needed. If it doesn't fit your case, or you want to add additional 677 * headers just call the public apis directly yourself for what you want. 678 * 679 * You can miss out the content length header by providing the constant 680 * LWS_ILLEGAL_HTTP_CONTENT_LEN for the content_len. 681 * 682 * It does not call lws_finalize_http_header(), to allow you to add further 683 * headers after calling this. You will need to call that yourself at the end. 684 */ 685 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 686 lws_add_http_common_headers(struct lws *wsi, unsigned int code, 687 const char *content_type, lws_filepos_t content_len, 688 unsigned char **p, unsigned char *end); 689 690 enum { 691 LWSHUMETH_GET, 692 LWSHUMETH_POST, 693 LWSHUMETH_OPTIONS, 694 LWSHUMETH_PUT, 695 LWSHUMETH_PATCH, 696 LWSHUMETH_DELETE, 697 LWSHUMETH_CONNECT, 698 LWSHUMETH_HEAD, 699 LWSHUMETH_COLON_PATH, 700 }; 701 702 /** 703 * lws_http_get_uri_and_method() - Get information on method and url 704 * 705 * \param wsi: the connection to get information on 706 * \param puri_ptr: points to pointer to set to url 707 * \param puri_len: points to int to set to uri length 708 * 709 * Returns -1 or method index as one of the LWSHUMETH_ constants 710 * 711 * If returns method, *puri_ptr is set to the method's URI string and *puri_len 712 * to its length 713 */ 714 715 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 716 lws_http_get_uri_and_method(struct lws *wsi, char **puri_ptr, int *puri_len); 717 718 ///@} 719 720 /*! \defgroup urlendec Urlencode and Urldecode 721 * \ingroup http 722 * 723 * ##HTML chunked Substitution 724 * 725 * APIs for receiving chunks of text, replacing a set of variable names via 726 * a callback, and then prepending and appending HTML chunked encoding 727 * headers. 728 */ 729 //@{ 730 731 /** 732 * lws_urlencode() - like strncpy but with urlencoding 733 * 734 * \param escaped: output buffer 735 * \param string: input buffer ('/0' terminated) 736 * \param len: output buffer max length 737 * 738 * Because urlencoding expands the output string, it's not 739 * possible to do it in-place, ie, with escaped == string 740 */ 741 LWS_VISIBLE LWS_EXTERN const char * 742 lws_urlencode(char *escaped, const char *string, int len); 743 744 /* 745 * URLDECODE 1 / 2 746 * 747 * This simple urldecode only operates until the first '\0' and requires the 748 * data to exist all at once 749 */ 750 /** 751 * lws_urldecode() - like strncpy but with urldecoding 752 * 753 * \param string: output buffer 754 * \param escaped: input buffer ('\0' terminated) 755 * \param len: output buffer max length 756 * 757 * This is only useful for '\0' terminated strings 758 * 759 * Since urldecoding only shrinks the output string, it is possible to 760 * do it in-place, ie, string == escaped 761 * 762 * Returns 0 if completed OK or nonzero for urldecode violation (non-hex chars 763 * where hex required, etc) 764 */ 765 LWS_VISIBLE LWS_EXTERN int 766 lws_urldecode(char *string, const char *escaped, int len); 767 ///@} 768 769 /** 770 * lws_http_date_render_from_unix() - render unixtime as RFC7231 date string 771 * 772 * \param buf: Destination string buffer 773 * \param len: avilable length of dest string buffer in bytes 774 * \param t: pointer to the time_t to render 775 * 776 * Returns 0 if time_t is rendered into the string buffer successfully, else 777 * nonzero. 778 */ 779 LWS_VISIBLE LWS_EXTERN int 780 lws_http_date_render_from_unix(char *buf, size_t len, const time_t *t); 781 782 /** 783 * lws_http_date_parse_unix() - parse a RFC7231 date string into unixtime 784 * 785 * \param b: Source string buffer 786 * \param len: avilable length of source string buffer in bytes 787 * \param t: pointer to the destination time_t to set 788 * 789 * Returns 0 if string buffer parsed as RFC7231 time successfully, and 790 * *t set to the parsed unixtime, else return nonzero. 791 */ 792 LWS_VISIBLE LWS_EXTERN int 793 lws_http_date_parse_unix(const char *b, size_t len, time_t *t); 794 795 /** 796 * lws_http_check_retry_after() - increase a timeout if retry-after present 797 * 798 * \param wsi: http stream this relates to 799 * \param us_interval_in_out: default us retry interval on entry may be updated 800 * 801 * This function may extend the incoming retry interval if the server has 802 * requested that using retry-after: header. It won't reduce the incoming 803 * retry interval, only leave it alone or increase it. 804 * 805 * *us_interval_in_out should be set to a default retry interval on entry, if 806 * the wsi has a retry-after time or interval that resolves to an interval 807 * longer than the entry *us_interval_in_out, that will be updated to the longer 808 * interval and return 0. 809 * 810 * If no usable retry-after or the time is now or in the past, 811 * *us_interval_in_out is left alone and the function returns nonzero. 812 */ 813 LWS_VISIBLE LWS_EXTERN int 814 lws_http_check_retry_after(struct lws *wsi, lws_usec_t *us_interval_in_out); 815 816 /** 817 * lws_return_http_status() - Return simple http status 818 * \param wsi: Websocket instance (available from user callback) 819 * \param code: Status index, eg, 404 820 * \param html_body: User-readable HTML description < 1KB, or NULL 821 * 822 * Helper to report HTTP errors back to the client cleanly and 823 * consistently 824 */ 825 LWS_VISIBLE LWS_EXTERN int 826 lws_return_http_status(struct lws *wsi, unsigned int code, 827 const char *html_body); 828 829 /** 830 * lws_http_redirect() - write http redirect out on wsi 831 * 832 * \param wsi: websocket connection 833 * \param code: HTTP response code (eg, 301) 834 * \param loc: where to redirect to 835 * \param len: length of loc 836 * \param p: pointer current position in buffer (updated as we write) 837 * \param end: pointer to end of buffer 838 * 839 * Returns amount written, or < 0 indicating fatal write failure. 840 */ 841 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 842 lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len, 843 unsigned char **p, unsigned char *end); 844 845 /** 846 * lws_http_transaction_completed() - wait for new http transaction or close 847 * \param wsi: websocket connection 848 * 849 * Returns 1 if the HTTP connection must close now 850 * Returns 0 and resets connection to wait for new HTTP header / 851 * transaction if possible 852 */ 853 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 854 lws_http_transaction_completed(struct lws *wsi); 855 856 /** 857 * lws_http_headers_detach() - drop the associated headers storage and allow 858 * it to be reused by another connection 859 * \param wsi: http connection 860 * 861 * If the wsi has an ah headers struct attached, detach it. 862 */ 863 LWS_VISIBLE LWS_EXTERN int 864 lws_http_headers_detach(struct lws *wsi); 865 866 /** 867 * lws_http_mark_sse() - called to indicate this http stream is now doing SSE 868 * 869 * \param wsi: http connection 870 * 871 * Cancel any timeout on the wsi, and for h2, mark the network connection as 872 * containing an immortal stream for the duration the SSE stream is open. 873 */ 874 LWS_VISIBLE LWS_EXTERN int 875 lws_http_mark_sse(struct lws *wsi); 876 877 /** 878 * lws_h2_client_stream_long_poll_rxonly() - h2 stream to immortal read-only 879 * 880 * \param wsi: h2 stream client wsi 881 * 882 * Send END_STREAM-flagged zero-length DATA frame to set client stream wsi into 883 * half-closed (local) and remote into half-closed (remote). Set the client 884 * stream wsi to be immortal (not subject to timeouts). 885 * 886 * Used if the remote server supports immortal long poll to put the stream into 887 * a read-only state where it can wait as long as needed for rx. 888 * 889 * Returns 0 if the process (which happens asynchronously) started or non-zero 890 * if it wasn't an h2 stream. 891 */ 892 LWS_VISIBLE LWS_EXTERN int 893 lws_h2_client_stream_long_poll_rxonly(struct lws *wsi); 894 895 /** 896 * lws_http_compression_apply() - apply an http compression transform 897 * 898 * \param wsi: the wsi to apply the compression transform to 899 * \param name: NULL, or the name of the compression transform, eg, "deflate" 900 * \param p: pointer to pointer to headers buffer 901 * \param end: pointer to end of headers buffer 902 * \param decomp: 0 = add compressor to wsi, 1 = add decompressor 903 * 904 * This allows transparent compression of dynamically generated HTTP. The 905 * requested compression (eg, "deflate") is only applied if the client headers 906 * indicated it was supported (and it has support in lws), otherwise it's a NOP. 907 * 908 * If the requested compression method is NULL, then the supported compression 909 * formats are tried, and for non-decompression (server) mode the first that's 910 * found on the client's accept-encoding header is chosen. 911 * 912 * NOTE: the compression transform, same as h2 support, relies on the user 913 * code using LWS_WRITE_HTTP and then LWS_WRITE_HTTP_FINAL on the last part 914 * written. The internal lws fileserving code already does this. 915 * 916 * If the library was built without the cmake option 917 * LWS_WITH_HTTP_STREAM_COMPRESSION set, then a NOP is provided for this api, 918 * allowing user code to build either way and use compression if available. 919 */ 920 LWS_VISIBLE LWS_EXTERN int 921 lws_http_compression_apply(struct lws *wsi, const char *name, 922 unsigned char **p, unsigned char *end, char decomp); 923 924 /** 925 * lws_http_is_redirected_to_get() - true if redirected to GET 926 * 927 * \param wsi: the wsi to check 928 * 929 * Check if the wsi is currently in GET mode, after, eg, doing a POST and 930 * receiving a 303. 931 */ 932 LWS_VISIBLE LWS_EXTERN int 933 lws_http_is_redirected_to_get(struct lws *wsi); 934 935 /** 936 * lws_http_cookie_get() - return copy of named cookie if present 937 * 938 * \param wsi: the wsi to check 939 * \param name: name of the cookie 940 * \param buf: buffer to store the cookie contents into 941 * \param max_len: on entry, maximum length of buf... on exit, used len of buf 942 * 943 * If no cookie header, or no cookie of the requested name, or the value is 944 * larger than can fit in buf, returns nonzero. 945 * 946 * If the cookie is found, copies its value into buf with a terminating NUL, 947 * sets *max_len to the used length, and returns 0. 948 * 949 * This handles the parsing of the possibly multi-cookie header string and 950 * terminating the requested cookie at the next ; if present. 951 */ 952 LWS_VISIBLE LWS_EXTERN int 953 lws_http_cookie_get(struct lws *wsi, const char *name, char *buf, size_t *max); 954 955 /** 956 * lws_http_client_http_error() - determine if the response code indicates an error 957 * 958 * \param code: the response code to test 959 * 960 * Returns nonzero if the code indicates an error, else zero if reflects a 961 * non-error condition 962 */ 963 #define lws_http_client_http_resp_is_error(code) (!(code < 400)) 964 965 /** 966 * lws_h2_update_peer_txcredit() - manually update stream peer tx credit 967 * 968 * \param wsi: the h2 child stream whose peer credit to change 969 * \param sid: the stream ID, or LWS_H2_STREAM_SID for the wsi stream ID 970 * \param bump: signed change to confer upon peer tx credit for sid 971 * 972 * In conjunction with LCCSCF_H2_MANUAL_RXFLOW flag, allows the user code to 973 * selectively starve the remote peer of the ability to send us data on a client 974 * connection. 975 * 976 * Normally lws sends an initial window size for the peer to send to it of 0, 977 * but during the header phase it sends a WINDOW_UPDATE to increase the amount 978 * available. LCCSCF_H2_MANUAL_RXFLOW restricts this initial increase in tx 979 * credit for the stream, before it has been asked to send us anything, to the 980 * amount specified in the client info .manual_initial_tx_credit member, and 981 * this api can be called to send the other side permission to send us up to 982 * \p bump additional bytes. 983 * 984 * The nwsi tx credit is updated automatically for exactly what was sent to us 985 * on a stream with LCCSCF_H2_MANUAL_RXFLOW flag, but the stream's own tx credit 986 * must be handled manually by user code via this api. 987 * 988 * Returns 0 for success or nonzero for failure. 989 */ 990 #define LWS_H2_STREAM_SID -1 991 LWS_VISIBLE LWS_EXTERN int 992 lws_h2_update_peer_txcredit(struct lws *wsi, unsigned int sid, int bump); 993 994 995 /** 996 * lws_h2_get_peer_txcredit_estimate() - return peer tx credit estimate 997 * 998 * \param wsi: the h2 child stream whose peer credit estimate to return 999 * 1000 * Returns the estimated amount of tx credit at the peer, in other words the 1001 * number of bytes the peer is authorized to send to us. 1002 * 1003 * It's an 'estimate' because we don't know how much is already in flight 1004 * towards us and actually already used. 1005 */ 1006 LWS_VISIBLE LWS_EXTERN int 1007 lws_h2_get_peer_txcredit_estimate(struct lws *wsi); 1008 1009 ///@} 1010 1011