CCU_TEST_09_04/include/libwebsockets/lws-conmon.h

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2021 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.
 */

/** \defgroup conmon Connection Latency information
 * ## Connection Latency information
 *
 * When LWS_WITH_CONMON is enabled at build, collects detailed statistics
 * about the client connection setup latency, available to the connection
 * itself
 */
///@{

/* enough for 4191s, or just over an hour */
typedef uint32_t lws_conmon_interval_us_t;

/*
 * Connection latency information... note that not all wsi actually make
 * connections, for example h2 streams after the initial one will have 0
 * for everything except ciu_txn_resp.
 *
 * If represented in JSON, it should look like this
 *
 *     {
 *        "peer": "46.105.127.147",
 *        "dns_us": 1234,
 *        "dns_disp": 1,
 *        "sockconn_us": 1234,
 *        "tls_us": 1234,
 *        "txn_resp_us": 1234,
 *        "dns":["46.105.127.147", "2001:41d0:2:ee93::1"],
 *        "prot_specific": {
 *        	"protocol": "http",
 *        	"resp": 200
 *        }
 *      }
 *
 * The indexes in "dns_disp" are declared in lws_conmon_dns_disposition_t
 * below.
 *
 * "prot_specific" may not be present if the protocol doesn't have anything
 * to report or is not supported.
 */

typedef enum lws_conmon_pcol {
	LWSCONMON_PCOL_NONE,
	LWSCONMON_PCOL_HTTP, /* .protocol_specific.http is valid */
} lws_conmon_pcol_t;

typedef enum lws_conmon_dns_disposition {
	LWSCONMON_DNS_NONE,
	/**< did not attempt DNS */
	LWSCONMON_DNS_OK				= 1,
	/**< DNS lookup did give results */
	LWSCONMON_DNS_SERVER_UNREACHABLE		= 2,
	/**< DNS server was not reachable */
	LWSCONMON_DNS_NO_RESULT				= 3
	/**< DNS server replied but nothing usable */
} lws_conmon_dns_disposition_t;

struct lws_conmon {
	lws_sockaddr46				peer46;
	/**< The peer we actually connected to, if any.  .peer46.sa4.sa_family
	 * is either 0 if invalid, or the AF_ */

	union {
		struct {
			int	response;
			/**< h1 http response code */
		} http;
	} protocol_specific;
	/**< possibly-present protocol-specific additional information.  This
	 * is only valid for the first transaction after connection and does
	 * not capture results for persistent or muxed connections like ws
	 * messages, mqtt messages, or h2 streams */

	struct addrinfo				*dns_results_copy;
	/**< NULL, or Allocated copy of dns results, owned by this object and
	 * freed when object destroyed.
	 * Only set if client flag LCCSCF_CONMON applied  */

	lws_conmon_interval_us_t		ciu_dns;
	/**< 0, or if a socket connection, us taken to acquire this DNS response
	 *
	 */
	lws_conmon_interval_us_t		ciu_sockconn;
	/**< 0, or if connection-based, the us interval between the socket
	 * connect() attempt that succeeded, and the connection setup */
	lws_conmon_interval_us_t		ciu_tls;
	/**< 0 if no tls, or us taken to establish the tls tunnel */
	lws_conmon_interval_us_t		ciu_txn_resp;
	/**< 0, or if the protocol supports transactions, the interval between
	 * sending the initial transaction request and starting to receive the
	 * response */

	lws_conmon_pcol_t			pcol;
	/**< indicates which extra protocol_specific info member is valid,
	 *   if any */

	lws_conmon_dns_disposition_t		dns_disposition;
	/**< indicates general disposition of DNS request */
};

/**
 * lws_conmon_wsi_take() - create a connection latency object from client wsi
 *
 * \param context: lws wsi
 * \param dest: conmon struct to fill
 *
 * Copies wsi conmon data into the caller's struct.  Passes ownership of
 * any allocations in the addrinfo list to the caller, lws will not delete that
 * any more on wsi close after this call.  The caller must call
 * lws_conmon_release() on the struct to destroy any addrinfo in the struct
 * that is prepared by this eventually but it can defer it as long as it wants.
 *
 * Other than the addrinfo list, the contents of the returned object are
 * completely selfcontained and don't point outside of the object itself, ie,
 * everything else in there remains in scope while the object itself does.
 */
LWS_VISIBLE LWS_EXTERN void
lws_conmon_wsi_take(struct lws *wsi, struct lws_conmon *dest);

/**
 * lws_conmon_release() - free any allocations in the conmon struct
 *
 * \param conmon: pointer to conmon struct
 *
 * Destroys any allocations in the conmon struct so it can go out of scope.
 * It doesn't free \p dest itself, it's designed to clean out a struct that
 * is on the stack or embedded in another object.
 */
LWS_VISIBLE LWS_EXTERN void
lws_conmon_release(struct lws_conmon *conmon);

///@}