Onek8/LNXCORE
1
0
Fork 0
Code Pull Requests Activity
LNXCORE/v8/include/libwebsockets/lws-http.h
Onek8 4c5e729485 Update Files
2025-01-22 17:22:38 +01:00

1030 lines
36 KiB
C
Raw Blame History

/*
* libwebsockets - small server side websockets and web server implementation
*
* Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*/
/* minimal space for typical headers and CSP stuff */
#define LWS_RECOMMENDED_MIN_HEADER_SPACE 2048
/*! \defgroup http HTTP
Modules related to handling HTTP
*/
//@{
/*! \defgroup httpft HTTP File transfer
* \ingroup http
APIs for sending local files in response to HTTP requests
*/
//@{
/**
* lws_get_mimetype() - Determine mimetype to use from filename
*
* \param file: filename
* \param m: NULL, or mount context
*
* This uses a canned list of known filetypes first, if no match and m is
* non-NULL, then tries a list of per-mount file suffix to mimtype mappings.
*
* Returns either NULL or a pointer to the mimetype matching the file.
*/
LWS_VISIBLE LWS_EXTERN const char *
lws_get_mimetype(const char *file, const struct lws_http_mount *m);
/**
* lws_serve_http_file() - Send a file back to the client using http
* \param wsi: Websocket instance (available from user callback)
* \param file: The file to issue over http
* \param content_type: The http content type, eg, text/html
* \param other_headers: NULL or pointer to header string
* \param other_headers_len: length of the other headers if non-NULL
*
* This function is intended to be called from the callback in response
* to http requests from the client. It allows the callback to issue
* local files down the http link in a single step.
*
* Returning <0 indicates error and the wsi should be closed. Returning
* >0 indicates the file was completely sent and
* lws_http_transaction_completed() called on the wsi (and close if != 0)
* ==0 indicates the file transfer is started and needs more service later,
* the wsi should be left alone.
*/
LWS_VISIBLE LWS_EXTERN int
lws_serve_http_file(struct lws *wsi, const char *file, const char *content_type,
const char *other_headers, int other_headers_len);
LWS_VISIBLE LWS_EXTERN int
lws_serve_http_file_fragment(struct lws *wsi);
//@}
enum http_status {
HTTP_STATUS_CONTINUE = 100,
HTTP_STATUS_OK = 200,
HTTP_STATUS_NO_CONTENT = 204,
HTTP_STATUS_PARTIAL_CONTENT = 206,
HTTP_STATUS_MOVED_PERMANENTLY = 301,
HTTP_STATUS_FOUND = 302,
HTTP_STATUS_SEE_OTHER = 303,
HTTP_STATUS_NOT_MODIFIED = 304,
HTTP_STATUS_BAD_REQUEST = 400,
HTTP_STATUS_UNAUTHORIZED,
HTTP_STATUS_PAYMENT_REQUIRED,
HTTP_STATUS_FORBIDDEN,
HTTP_STATUS_NOT_FOUND,
HTTP_STATUS_METHOD_NOT_ALLOWED,
HTTP_STATUS_NOT_ACCEPTABLE,
HTTP_STATUS_PROXY_AUTH_REQUIRED,
HTTP_STATUS_REQUEST_TIMEOUT,
HTTP_STATUS_CONFLICT,
HTTP_STATUS_GONE,
HTTP_STATUS_LENGTH_REQUIRED,
HTTP_STATUS_PRECONDITION_FAILED,
HTTP_STATUS_REQ_ENTITY_TOO_LARGE,
HTTP_STATUS_REQ_URI_TOO_LONG,
HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE,
HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE,
HTTP_STATUS_EXPECTATION_FAILED,
HTTP_STATUS_INTERNAL_SERVER_ERROR = 500,
HTTP_STATUS_NOT_IMPLEMENTED,
HTTP_STATUS_BAD_GATEWAY,
HTTP_STATUS_SERVICE_UNAVAILABLE,
HTTP_STATUS_GATEWAY_TIMEOUT,
HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED,
};
/*! \defgroup html-chunked-substitution HTML Chunked Substitution
* \ingroup http
*
* ##HTML chunked Substitution
*
* APIs for receiving chunks of text, replacing a set of variable names via
* a callback, and then prepending and appending HTML chunked encoding
* headers.
*/
//@{
struct lws_process_html_args {
char *p; /**< pointer to the buffer containing the data */
int len; /**< length of the original data at p */
int max_len; /**< maximum length we can grow the data to */
int final; /**< set if this is the last chunk of the file */
int chunked; /**< 0 == unchunked, 1 == produce chunk headers
(incompatible with HTTP/2) */
};
typedef const char *(*lws_process_html_state_cb)(void *data, int index);
struct lws_process_html_state {
char *start; /**< pointer to start of match */
char swallow[16]; /**< matched character buffer */
int pos; /**< position in match */
void *data; /**< opaque pointer */
const char * const *vars; /**< list of variable names */
int count_vars; /**< count of variable names */
lws_process_html_state_cb replace;
/**< called on match to perform substitution */
};
/*! lws_chunked_html_process() - generic chunked substitution
* \param args: buffer to process using chunked encoding
* \param s: current processing state
*/
LWS_VISIBLE LWS_EXTERN int
lws_chunked_html_process(struct lws_process_html_args *args,
struct lws_process_html_state *s);
//@}
/** \defgroup HTTP-headers-read HTTP headers: read
* \ingroup http
*
* ##HTTP header releated functions
*
* In lws the client http headers are temporarily stored in a pool, only for the
* duration of the http part of the handshake. It's because in most cases,
* the header content is ignored for the whole rest of the connection lifetime
* and would then just be taking up space needlessly.
*
* During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
* the http headers are still allocated, you can use these apis then to
* look at and copy out interesting header content (cookies, etc)
*
* Notice that the header total length reported does not include a terminating
* '\0', however you must allocate for it when using the _copy apis. So the
* length reported for a header containing "123" is 3, but you must provide
* a buffer of length 4 so that "123\0" may be copied into it, or the copy
* will fail with a nonzero return code.
*
* In the special case of URL arguments, like ?x=1&y=2, the arguments are
* stored in a token named for the method, eg, WSI_TOKEN_GET_URI if it
* was a GET or WSI_TOKEN_POST_URI if POST. You can check the total
* length to confirm the method.
*
* For URL arguments, each argument is stored urldecoded in a "fragment", so
* you can use the fragment-aware api lws_hdr_copy_fragment() to access each
* argument in turn: the fragments contain urldecoded strings like x=1 or y=2.
*
* As a convenience, lws has an api that will find the fragment with a
* given name= part, lws_get_urlarg_by_name().
*/
///@{
/** struct lws_tokens
* you need these to look at headers that have been parsed if using the
* LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
* list below is absent, .token = NULL and len = 0. Otherwise .token
* points to .len chars containing that header content.
*/
struct lws_tokens {
unsigned char *token; /**< pointer to start of the token */
int len; /**< length of the token's value */
};
/* enum lws_token_indexes
* these have to be kept in sync with lextable.h / minilex.c
*
* NOTE: These public enums are part of the abi. If you want to add one,
* add it at where specified so existing users are unaffected.
*/
enum lws_token_indexes {
WSI_TOKEN_GET_URI, /* 0 */
WSI_TOKEN_POST_URI,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_OPTIONS_URI,
#endif
WSI_TOKEN_HOST,
WSI_TOKEN_CONNECTION,
WSI_TOKEN_UPGRADE, /* 5 */
WSI_TOKEN_ORIGIN,
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_DRAFT,
#endif
WSI_TOKEN_CHALLENGE,
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_EXTENSIONS,
WSI_TOKEN_KEY1, /* 10 */
WSI_TOKEN_KEY2,
WSI_TOKEN_PROTOCOL,
WSI_TOKEN_ACCEPT,
WSI_TOKEN_NONCE,
#endif
WSI_TOKEN_HTTP,
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP2_SETTINGS, /* 16 */
#endif
WSI_TOKEN_HTTP_ACCEPT,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_AC_REQUEST_HEADERS,
#endif
WSI_TOKEN_HTTP_IF_MODIFIED_SINCE,
WSI_TOKEN_HTTP_IF_NONE_MATCH, /* 20 */
WSI_TOKEN_HTTP_ACCEPT_ENCODING,
WSI_TOKEN_HTTP_ACCEPT_LANGUAGE,
WSI_TOKEN_HTTP_PRAGMA,
WSI_TOKEN_HTTP_CACHE_CONTROL,
WSI_TOKEN_HTTP_AUTHORIZATION,
WSI_TOKEN_HTTP_COOKIE,
WSI_TOKEN_HTTP_CONTENT_LENGTH, /* 27 */
WSI_TOKEN_HTTP_CONTENT_TYPE,
WSI_TOKEN_HTTP_DATE,
WSI_TOKEN_HTTP_RANGE,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_REFERER,
#endif
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_KEY,
WSI_TOKEN_VERSION,
WSI_TOKEN_SWORIGIN,
#endif
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_COLON_AUTHORITY,
WSI_TOKEN_HTTP_COLON_METHOD,
WSI_TOKEN_HTTP_COLON_PATH,
WSI_TOKEN_HTTP_COLON_SCHEME,
WSI_TOKEN_HTTP_COLON_STATUS,
#endif
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_ACCEPT_CHARSET,
#endif
WSI_TOKEN_HTTP_ACCEPT_RANGES,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN,
#endif
WSI_TOKEN_HTTP_AGE,
WSI_TOKEN_HTTP_ALLOW,
WSI_TOKEN_HTTP_CONTENT_DISPOSITION,
WSI_TOKEN_HTTP_CONTENT_ENCODING,
WSI_TOKEN_HTTP_CONTENT_LANGUAGE,
WSI_TOKEN_HTTP_CONTENT_LOCATION,
WSI_TOKEN_HTTP_CONTENT_RANGE,
WSI_TOKEN_HTTP_ETAG,
WSI_TOKEN_HTTP_EXPECT,
WSI_TOKEN_HTTP_EXPIRES,
WSI_TOKEN_HTTP_FROM,
WSI_TOKEN_HTTP_IF_MATCH,
WSI_TOKEN_HTTP_IF_RANGE,
WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE,
WSI_TOKEN_HTTP_LAST_MODIFIED,
WSI_TOKEN_HTTP_LINK,
WSI_TOKEN_HTTP_LOCATION,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_MAX_FORWARDS,
WSI_TOKEN_HTTP_PROXY_AUTHENTICATE,
WSI_TOKEN_HTTP_PROXY_AUTHORIZATION,
#endif
WSI_TOKEN_HTTP_REFRESH,
WSI_TOKEN_HTTP_RETRY_AFTER,
WSI_TOKEN_HTTP_SERVER,
WSI_TOKEN_HTTP_SET_COOKIE,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY,
#endif
WSI_TOKEN_HTTP_TRANSFER_ENCODING,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_HTTP_USER_AGENT,
WSI_TOKEN_HTTP_VARY,
WSI_TOKEN_HTTP_VIA,
WSI_TOKEN_HTTP_WWW_AUTHENTICATE,
#endif
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_PATCH_URI,
WSI_TOKEN_PUT_URI,
WSI_TOKEN_DELETE_URI,
#endif
WSI_TOKEN_HTTP_URI_ARGS,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_PROXY,
WSI_TOKEN_HTTP_X_REAL_IP,
#endif
WSI_TOKEN_HTTP1_0,
WSI_TOKEN_X_FORWARDED_FOR,
WSI_TOKEN_CONNECT,
WSI_TOKEN_HEAD_URI,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_TE,
WSI_TOKEN_REPLAY_NONCE, /* ACME */
#endif
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_COLON_PROTOCOL,
#endif
WSI_TOKEN_X_AUTH_TOKEN,
WSI_TOKEN_DSS_SIGNATURE,
/****** add new things just above ---^ ******/
/* use token storage to stash these internally, not for
* user use */
_WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
_WSI_TOKEN_CLIENT_PEER_ADDRESS,
_WSI_TOKEN_CLIENT_URI,
_WSI_TOKEN_CLIENT_HOST,
_WSI_TOKEN_CLIENT_ORIGIN,
_WSI_TOKEN_CLIENT_METHOD,
_WSI_TOKEN_CLIENT_IFACE,
_WSI_TOKEN_CLIENT_LOCALPORT,
_WSI_TOKEN_CLIENT_ALPN,
/* always last real token index*/
WSI_TOKEN_COUNT,
/* parser state additions, no storage associated */
WSI_TOKEN_NAME_PART,
#if defined(LWS_WITH_CUSTOM_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
WSI_TOKEN_UNKNOWN_VALUE_PART,
#endif
WSI_TOKEN_SKIPPING,
WSI_TOKEN_SKIPPING_SAW_CR,
WSI_PARSING_COMPLETE,
WSI_INIT_TOKEN_MUXURL,
};
struct lws_token_limits {
unsigned short token_limit[WSI_TOKEN_COUNT]; /**< max chars for this token */
};
enum lws_h2_settings {
H2SET_HEADER_TABLE_SIZE = 1,
H2SET_ENABLE_PUSH,
H2SET_MAX_CONCURRENT_STREAMS,
H2SET_INITIAL_WINDOW_SIZE,
H2SET_MAX_FRAME_SIZE,
H2SET_MAX_HEADER_LIST_SIZE,
H2SET_RESERVED7,
H2SET_ENABLE_CONNECT_PROTOCOL, /* defined in mcmanus-httpbis-h2-ws-02 */
H2SET_COUNT /* always last */
};
/**
* lws_token_to_string() - returns a textual representation of a hdr token index
*
* \param token: token index
*/
LWS_VISIBLE LWS_EXTERN const unsigned char *
lws_token_to_string(enum lws_token_indexes token);
/**
* lws_hdr_total_length: report length of all fragments of a header totalled up
* The returned length does not include the space for a
* terminating '\0'
*
* \param wsi: websocket connection
* \param h: which header index we are interested in
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h);
/**
* lws_hdr_fragment_length: report length of a single fragment of a header
* The returned length does not include the space for a
* terminating '\0'
*
* \param wsi: websocket connection
* \param h: which header index we are interested in
* \param frag_idx: which fragment of h we want to get the length of
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h,
int frag_idx);
/**
* lws_hdr_copy() - copy all fragments of the given header to a buffer
* The buffer length len must include space for an additional
* terminating '\0', or it will fail returning -1.
*
* \param wsi: websocket connection
* \param dest: destination buffer
* \param len: length of destination buffer
* \param h: which header index we are interested in
*
* copies the whole, aggregated header, even if it was delivered in
* several actual headers piece by piece. Returns -1 or length of the whole
* header.
*/
LWS_VISIBLE LWS_EXTERN int
lws_hdr_copy(struct lws *wsi, char *dest, int len, enum lws_token_indexes h);
/**
* lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer
* The buffer length len must include space for an additional
* terminating '\0', or it will fail returning -2.
* If the requested fragment index is not present, it fails
* returning -1.
*
* \param wsi: websocket connection
* \param dest: destination buffer
* \param len: length of destination buffer
* \param h: which header index we are interested in
* \param frag_idx: which fragment of h we want to copy
*
* Normally this is only useful
* to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS
* fragment 0 will contain "x=1" and fragment 1 "y=2"
*/
LWS_VISIBLE LWS_EXTERN int
lws_hdr_copy_fragment(struct lws *wsi, char *dest, int len,
enum lws_token_indexes h, int frag_idx);
/**
* lws_hdr_custom_length() - return length of a custom header
*
* \param wsi: websocket connection
* \param name: header string (including terminating :)
* \param nlen: length of name
*
* Lws knows about 100 common http headers, and parses them into indexes when
* it recognizes them. When it meets a header that it doesn't know, it stores
* the name and value directly, and you can look them up using
* lws_hdr_custom_length() and lws_hdr_custom_copy().
*
* This api returns -1, or the length of the value part of the header if it
* exists. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to
* use this api.
*/
LWS_VISIBLE LWS_EXTERN int
lws_hdr_custom_length(struct lws *wsi, const char *name, int nlen);
/**
* lws_hdr_custom_copy() - copy value part of a custom header
*
* \param wsi: websocket connection
* \param dst: pointer to buffer to receive the copy
* \param len: number of bytes available at dst
* \param name: header string (including terminating :)
* \param nlen: length of name
*
* Lws knows about 100 common http headers, and parses them into indexes when
* it recognizes them. When it meets a header that it doesn't know, it stores
* the name and value directly, and you can look them up using
* lws_hdr_custom_length() and lws_hdr_custom_copy().
*
* This api returns -1, or the length of the string it copied into dst if it
* was big enough to contain both the string and an extra terminating NUL. Lws
* must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api.
*/
LWS_VISIBLE LWS_EXTERN int
lws_hdr_custom_copy(struct lws *wsi, char *dst, int len, const char *name,
int nlen);
typedef void (*lws_hdr_custom_fe_cb_t)(const char *name, int nlen, void *opaque);
/**
* lws_hdr_custom_name_foreach() - Iterate the custom header names
*
* \param wsi: websocket connection
* \param cb: callback for each custom header name
* \param opaque: ignored by lws except to pass to callback
*
* Lws knows about 100 common http headers, and parses them into indexes when
* it recognizes them. When it meets a header that it doesn't know, it stores
* the name and value directly, and you can look them up using
* lws_hdr_custom_length() and lws_hdr_custom_copy().
*
* This api returns -1 on error else 0. Use lws_hdr_custom_copy() to get the
* values of headers. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by
* default) to use this api.
*/
LWS_VISIBLE LWS_EXTERN int
lws_hdr_custom_name_foreach(struct lws *wsi, lws_hdr_custom_fe_cb_t cb, void *opaque);
/**
* lws_get_urlarg_by_name_safe() - get copy and return length of y for x=y urlargs
*
* \param wsi: the connection to check
* \param name: the arg name, like "token" or "token="
* \param buf: the buffer to receive the urlarg (including the name= part)
* \param len: the length of the buffer to receive the urlarg
*
* Returns -1 if not present, else the length of y in the urlarg name=y. If
* zero or greater, then buf contains a copy of the string y. Any = after the
* name match is trimmed off if the name does not end with = itself.
*
* This returns the explicit length and so can deal with binary blobs that are
* percent-encoded. It also makes sure buf has a NUL just after the valid
* length so it can work with NUL-based apis if you don't care about truncation.
*
* buf may have been written even when -1 is returned indicating no match.
*
* Use this in place of lws_get_urlarg_by_name() that does not return an
* explicit length.
*/
LWS_VISIBLE LWS_EXTERN int
lws_get_urlarg_by_name_safe(struct lws *wsi, const char *name, char *buf, int len);
/**
* lws_get_urlarg_by_name() - return pointer to arg value if present
*
* \param wsi: the connection to check
* \param name: the arg name, like "token="
* \param buf: the buffer to receive the urlarg (including the name= part)
* \param len: the length of the buffer to receive the urlarg
*
* Returns NULL if not found or a pointer inside buf to just after the
* name= part.
*
* This assumed the argument can be represented with a NUL-terminated string.
* It can't correctly deal with binary values encoded with %XX, eg. %00 will
* be understood to terminate the string.
*
* Use lws_get_urlarg_by_name_safe() instead of this, which returns the length.
*/
LWS_VISIBLE LWS_EXTERN const char *
lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len)
/* LWS_WARN_DEPRECATED */;
///@}
/*! \defgroup HTTP-headers-create HTTP headers: create
*
* ## HTTP headers: Create
*
* These apis allow you to create HTTP response headers in a way compatible with
* both HTTP/1.x and HTTP/2.
*
* They each append to a buffer taking care about the buffer end, which is
* passed in as a pointer. When data is written to the buffer, the current
* position p is updated accordingly.
*
* All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space
* and fail with nonzero return.
*/
///@{
#define LWSAHH_CODE_MASK ((1 << 16) - 1)
#define LWSAHH_FLAG_NO_SERVER_NAME (1 << 30)
/**
* lws_add_http_header_status() - add the HTTP response status code
*
* \param wsi: the connection to check
* \param code: an HTTP code like 200, 404 etc (see enum http_status)
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Adds the initial response code, so should be called first.
*
* Code may additionally take OR'd flags:
*
* LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_add_http_header_status(struct lws *wsi,
unsigned int code, unsigned char **p,
unsigned char *end);
/**
* lws_add_http_header_by_name() - append named header and value
*
* \param wsi: the connection to check
* \param name: the hdr name, like "my-header:"
* \param value: the value after the = for this header
* \param length: the length of the value
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Appends name: value to the headers
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_add_http_header_by_name(struct lws *wsi, const unsigned char *name,
const unsigned char *value, int length,
unsigned char **p, unsigned char *end);
/**
* lws_add_http_header_by_token() - append given header and value
*
* \param wsi: the connection to check
* \param token: the token index for the hdr
* \param value: the value after the = for this header
* \param length: the length of the value
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Appends name=value to the headers, but is able to take advantage of better
* HTTP/2 coding mechanisms where possible.
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_add_http_header_by_token(struct lws *wsi, enum lws_token_indexes token,
const unsigned char *value, int length,
unsigned char **p, unsigned char *end);
/**
* lws_add_http_header_content_length() - append content-length helper
*
* \param wsi: the connection to check
* \param content_length: the content length to use
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Appends content-length: content_length to the headers
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_add_http_header_content_length(struct lws *wsi,
lws_filepos_t content_length,
unsigned char **p, unsigned char *end);
/**
* lws_finalize_http_header() - terminate header block
*
* \param wsi: the connection to check
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Indicates no more headers will be added
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_finalize_http_header(struct lws *wsi, unsigned char **p,
unsigned char *end);
/**
* lws_finalize_write_http_header() - Helper finializing and writing http headers
*
* \param wsi: the connection to check
* \param start: pointer to the start of headers in the buffer, eg &buf[LWS_PRE]
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Terminates the headers correctly accoring to the protocol in use (h1 / h2)
* and writes the headers. Returns nonzero for error.
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_finalize_write_http_header(struct lws *wsi, unsigned char *start,
unsigned char **p, unsigned char *end);
#define LWS_ILLEGAL_HTTP_CONTENT_LEN ((lws_filepos_t)-1ll)
/**
* lws_add_http_common_headers() - Helper preparing common http headers
*
* \param wsi: the connection to check
* \param code: an HTTP code like 200, 404 etc (see enum http_status)
* \param content_type: the content type, like "text/html"
* \param content_len: the content length, in bytes
* \param p: pointer to current position in buffer pointer
* \param end: pointer to end of buffer
*
* Adds the initial response code, so should be called first.
*
* Code may additionally take OR'd flags:
*
* LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time
*
* This helper just calls public apis to simplify adding headers that are
* commonly needed. If it doesn't fit your case, or you want to add additional
* headers just call the public apis directly yourself for what you want.
*
* You can miss out the content length header by providing the constant
* LWS_ILLEGAL_HTTP_CONTENT_LEN for the content_len.
*
* It does not call lws_finalize_http_header(), to allow you to add further
* headers after calling this. You will need to call that yourself at the end.
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_add_http_common_headers(struct lws *wsi, unsigned int code,
const char *content_type, lws_filepos_t content_len,
unsigned char **p, unsigned char *end);
enum {
LWSHUMETH_GET,
LWSHUMETH_POST,
LWSHUMETH_OPTIONS,
LWSHUMETH_PUT,
LWSHUMETH_PATCH,
LWSHUMETH_DELETE,
LWSHUMETH_CONNECT,
LWSHUMETH_HEAD,
LWSHUMETH_COLON_PATH,
};
/**
* lws_http_get_uri_and_method() - Get information on method and url
*
* \param wsi: the connection to get information on
* \param puri_ptr: points to pointer to set to url
* \param puri_len: points to int to set to uri length
*
* Returns -1 or method index as one of the LWSHUMETH_ constants
*
* If returns method, *puri_ptr is set to the method's URI string and *puri_len
* to its length
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_http_get_uri_and_method(struct lws *wsi, char **puri_ptr, int *puri_len);
///@}
/*! \defgroup urlendec Urlencode and Urldecode
* \ingroup http
*
* ##HTML chunked Substitution
*
* APIs for receiving chunks of text, replacing a set of variable names via
* a callback, and then prepending and appending HTML chunked encoding
* headers.
*/
//@{
/**
* lws_urlencode() - like strncpy but with urlencoding
*
* \param escaped: output buffer
* \param string: input buffer ('/0' terminated)
* \param len: output buffer max length
*
* Because urlencoding expands the output string, it's not
* possible to do it in-place, ie, with escaped == string
*/
LWS_VISIBLE LWS_EXTERN const char *
lws_urlencode(char *escaped, const char *string, int len);
/*
* URLDECODE 1 / 2
*
* This simple urldecode only operates until the first '\0' and requires the
* data to exist all at once
*/
/**
* lws_urldecode() - like strncpy but with urldecoding
*
* \param string: output buffer
* \param escaped: input buffer ('\0' terminated)
* \param len: output buffer max length
*
* This is only useful for '\0' terminated strings
*
* Since urldecoding only shrinks the output string, it is possible to
* do it in-place, ie, string == escaped
*
* Returns 0 if completed OK or nonzero for urldecode violation (non-hex chars
* where hex required, etc)
*/
LWS_VISIBLE LWS_EXTERN int
lws_urldecode(char *string, const char *escaped, int len);
///@}
/**
* lws_http_date_render_from_unix() - render unixtime as RFC7231 date string
*
* \param buf: Destination string buffer
* \param len: avilable length of dest string buffer in bytes
* \param t: pointer to the time_t to render
*
* Returns 0 if time_t is rendered into the string buffer successfully, else
* nonzero.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_date_render_from_unix(char *buf, size_t len, const time_t *t);
/**
* lws_http_date_parse_unix() - parse a RFC7231 date string into unixtime
*
* \param b: Source string buffer
* \param len: avilable length of source string buffer in bytes
* \param t: pointer to the destination time_t to set
*
* Returns 0 if string buffer parsed as RFC7231 time successfully, and
* *t set to the parsed unixtime, else return nonzero.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_date_parse_unix(const char *b, size_t len, time_t *t);
/**
* lws_http_check_retry_after() - increase a timeout if retry-after present
*
* \param wsi: http stream this relates to
* \param us_interval_in_out: default us retry interval on entry may be updated
*
* This function may extend the incoming retry interval if the server has
* requested that using retry-after: header. It won't reduce the incoming
* retry interval, only leave it alone or increase it.
*
* *us_interval_in_out should be set to a default retry interval on entry, if
* the wsi has a retry-after time or interval that resolves to an interval
* longer than the entry *us_interval_in_out, that will be updated to the longer
* interval and return 0.
*
* If no usable retry-after or the time is now or in the past,
* *us_interval_in_out is left alone and the function returns nonzero.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_check_retry_after(struct lws *wsi, lws_usec_t *us_interval_in_out);
/**
* lws_return_http_status() - Return simple http status
* \param wsi: Websocket instance (available from user callback)
* \param code: Status index, eg, 404
* \param html_body: User-readable HTML description < 1KB, or NULL
*
* Helper to report HTTP errors back to the client cleanly and
* consistently
*/
LWS_VISIBLE LWS_EXTERN int
lws_return_http_status(struct lws *wsi, unsigned int code,
const char *html_body);
/**
* lws_http_redirect() - write http redirect out on wsi
*
* \param wsi: websocket connection
* \param code: HTTP response code (eg, 301)
* \param loc: where to redirect to
* \param len: length of loc
* \param p: pointer current position in buffer (updated as we write)
* \param end: pointer to end of buffer
*
* Returns amount written, or < 0 indicating fatal write failure.
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
unsigned char **p, unsigned char *end);
/**
* lws_http_transaction_completed() - wait for new http transaction or close
* \param wsi: websocket connection
*
* Returns nonzero if the HTTP connection must close now
* Returns 0 and resets connection to wait for new HTTP header /
* transaction if possible
*/
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_http_transaction_completed(struct lws *wsi);
/**
* lws_http_headers_detach() - drop the associated headers storage and allow
* it to be reused by another connection
* \param wsi: http connection
*
* If the wsi has an ah headers struct attached, detach it.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_headers_detach(struct lws *wsi);
/**
* lws_http_mark_sse() - called to indicate this http stream is now doing SSE
*
* \param wsi: http connection
*
* Cancel any timeout on the wsi, and for h2, mark the network connection as
* containing an immortal stream for the duration the SSE stream is open.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_mark_sse(struct lws *wsi);
/**
* lws_h2_client_stream_long_poll_rxonly() - h2 stream to immortal read-only
*
* \param wsi: h2 stream client wsi
*
* Send END_STREAM-flagged zero-length DATA frame to set client stream wsi into
* half-closed (local) and remote into half-closed (remote). Set the client
* stream wsi to be immortal (not subject to timeouts).
*
* Used if the remote server supports immortal long poll to put the stream into
* a read-only state where it can wait as long as needed for rx.
*
* Returns 0 if the process (which happens asynchronously) started or non-zero
* if it wasn't an h2 stream.
*/
LWS_VISIBLE LWS_EXTERN int
lws_h2_client_stream_long_poll_rxonly(struct lws *wsi);
/**
* lws_http_compression_apply() - apply an http compression transform
*
* \param wsi: the wsi to apply the compression transform to
* \param name: NULL, or the name of the compression transform, eg, "deflate"
* \param p: pointer to pointer to headers buffer
* \param end: pointer to end of headers buffer
* \param decomp: 0 = add compressor to wsi, 1 = add decompressor
*
* This allows transparent compression of dynamically generated HTTP. The
* requested compression (eg, "deflate") is only applied if the client headers
* indicated it was supported (and it has support in lws), otherwise it's a NOP.
*
* If the requested compression method is NULL, then the supported compression
* formats are tried, and for non-decompression (server) mode the first that's
* found on the client's accept-encoding header is chosen.
*
* NOTE: the compression transform, same as h2 support, relies on the user
* code using LWS_WRITE_HTTP and then LWS_WRITE_HTTP_FINAL on the last part
* written. The internal lws fileserving code already does this.
*
* If the library was built without the cmake option
* LWS_WITH_HTTP_STREAM_COMPRESSION set, then a NOP is provided for this api,
* allowing user code to build either way and use compression if available.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_compression_apply(struct lws *wsi, const char *name,
unsigned char **p, unsigned char *end, char decomp);
/**
* lws_http_is_redirected_to_get() - true if redirected to GET
*
* \param wsi: the wsi to check
*
* Check if the wsi is currently in GET mode, after, eg, doing a POST and
* receiving a 303.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_is_redirected_to_get(struct lws *wsi);
/**
* lws_http_cookie_get() - return copy of named cookie if present
*
* \param wsi: the wsi to check
* \param name: name of the cookie
* \param buf: buffer to store the cookie contents into
* \param max_len: on entry, maximum length of buf... on exit, used len of buf
*
* If no cookie header, or no cookie of the requested name, or the value is
* larger than can fit in buf, returns nonzero.
*
* If the cookie is found, copies its value into buf with a terminating NUL,
* sets *max_len to the used length, and returns 0.
*
* This handles the parsing of the possibly multi-cookie header string and
* terminating the requested cookie at the next ; if present.
*/
LWS_VISIBLE LWS_EXTERN int
lws_http_cookie_get(struct lws *wsi, const char *name, char *buf, size_t *max);
/**
* lws_http_client_http_error() - determine if the response code indicates an error
*
* \param code: the response code to test
*
* Returns nonzero if the code indicates an error, else zero if reflects a
* non-error condition
*/
#define lws_http_client_http_resp_is_error(code) (!(code < 400))
/**
* lws_h2_update_peer_txcredit() - manually update stream peer tx credit
*
* \param wsi: the h2 child stream whose peer credit to change
* \param sid: the stream ID, or LWS_H2_STREAM_SID for the wsi stream ID
* \param bump: signed change to confer upon peer tx credit for sid
*
* In conjunction with LCCSCF_H2_MANUAL_RXFLOW flag, allows the user code to
* selectively starve the remote peer of the ability to send us data on a client
* connection.
*
* Normally lws sends an initial window size for the peer to send to it of 0,
* but during the header phase it sends a WINDOW_UPDATE to increase the amount
* available. LCCSCF_H2_MANUAL_RXFLOW restricts this initial increase in tx
* credit for the stream, before it has been asked to send us anything, to the
* amount specified in the client info .manual_initial_tx_credit member, and
* this api can be called to send the other side permission to send us up to
* \p bump additional bytes.
*
* The nwsi tx credit is updated automatically for exactly what was sent to us
* on a stream with LCCSCF_H2_MANUAL_RXFLOW flag, but the stream's own tx credit
* must be handled manually by user code via this api.
*
* Returns 0 for success or nonzero for failure.
*/
#define LWS_H2_STREAM_SID -1
LWS_VISIBLE LWS_EXTERN int
lws_h2_update_peer_txcredit(struct lws *wsi, unsigned int sid, int bump);
/**
* lws_h2_get_peer_txcredit_estimate() - return peer tx credit estimate
*
* \param wsi: the h2 child stream whose peer credit estimate to return
*
* Returns the estimated amount of tx credit at the peer, in other words the
* number of bytes the peer is authorized to send to us.
*
* It's an 'estimate' because we don't know how much is already in flight
* towards us and actually already used.
*/
LWS_VISIBLE LWS_EXTERN int
lws_h2_get_peer_txcredit_estimate(struct lws *wsi);
///@}
View Git Blame Copy Permalink