1 /** @file 2 3 Traffic Dump session handling encapsulation. 4 5 @section license License 6 7 Licensed to the Apache Software Foundation (ASF) under one 8 or more contributor license agreements. See the NOTICE file 9 distributed with this work for additional information 10 regarding copyright ownership. The ASF licenses this file 11 to you under the Apache License, Version 2.0 (the 12 "License"); you may not use this file except in compliance 13 with the License. You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 */ 23 24 #pragma once 25 26 #include <atomic> 27 #include <cstdlib> 28 #include <mutex> 29 #include <string> 30 #include <string_view> 31 #include <optional> 32 33 #include "ts/ts.h" 34 #include "tscore/ts_file.h" 35 36 namespace traffic_dump 37 { 38 /** The information associated with an individual session. 39 * 40 * This class is responsible for containing the members associated with a 41 * particular session and defines the session handler callback. 42 */ 43 class SessionData 44 { 45 public: 46 /// By default, Traffic Dump logs will go into a directory called "dump". 47 static char const constexpr *const default_log_directory = "dump"; 48 /// By default, 1 out of 1000 sessions will be dumped. 49 static constexpr int64_t default_sample_pool_size = 1000; 50 /// By default, logging will stop after 10 MB have been dumped. 51 static constexpr int64_t default_max_disk_usage = 10 * 1000 * 1000; 52 53 private: 54 // 55 // Instance Variables 56 // 57 58 /// Log file descriptor for this session's dump file. 59 int log_fd = -1; 60 /// The count of the currently outstanding AIO operations. 61 int aio_count = 0; 62 /// The offset of the last point written to so for in the dump file for this 63 /// session. 64 int64_t write_offset = 0; 65 /// Whether this session has been closed. 66 bool ssn_closed = false; 67 /// The filename for this session's dump file. 68 ts::file::path log_name; 69 /// Whether the first transaction in this session has been written. 70 bool has_written_first_transaction = false; 71 /// The HTTP version specified in the client protocol stack, or empty string 72 /// if it was not specified. 73 std::string http_version_in_client_stack; 74 75 TSCont aio_cont = nullptr; /// AIO continuation callback 76 TSCont txn_cont = nullptr; /// Transaction continuation callback 77 78 // The following has to be recursive because the stack does not unwind 79 // between event invocations. 80 std::recursive_mutex disk_io_mutex; /// The mutex for guarding IO calls. 81 82 // 83 // Static Variables 84 // 85 86 // The index to be used for the TS API for storing this SessionData on a 87 // per-session basis. 88 static int session_arg_index; 89 90 /// The rate at which to dump sessions. Every one out of sample_pool_size will 91 /// be dumped. 92 static std::atomic<int64_t> sample_pool_size; 93 /// The maximum space logs should take up before stopping the dumping of new 94 /// sessions. 95 static std::atomic<int64_t> max_disk_usage; 96 /// The amount of bytes currently written to dump files. 97 static std::atomic<int64_t> disk_usage; 98 99 /// The directory into which to put the dump files. 100 static ts::file::path log_directory; 101 102 /// Only sessions with this SNI will be dumped (if set). 103 static std::string sni_filter; 104 105 /// The running counter of all sessions dumped by traffic_dump. 106 static uint64_t session_counter; 107 108 public: 109 SessionData(); 110 ~SessionData(); 111 112 /** The getter for the session_arg_index value. */ 113 static int get_session_arg_index(); 114 115 /** Initialize the cross-session values of managing sessions. 116 * 117 * @return True if initialization is successful, false otherwise. 118 */ 119 static bool init(std::string_view log_directory, int64_t max_disk_usage, int64_t sample_size); 120 static bool init(std::string_view log_directory, int64_t max_disk_usage, int64_t sample_size, std::string_view sni_filter); 121 122 /** Set the sample_pool_size to a new value. 123 * 124 * @param[in] new_sample_size The new value to set for sample_pool_size. 125 */ 126 static void set_sample_pool_size(int64_t new_sample_size); 127 128 /** Reset the disk usage counter to 0. */ 129 static void reset_disk_usage(); 130 131 /** Set the max_disk_usage to a new value. 132 * 133 * @param[in] new_max_disk_usage The new value to set for max_disk_usage. 134 */ 135 static void set_max_disk_usage(int64_t new_max_disk_usage); 136 137 /** Get the JSON string that describes the server session stack. 138 * 139 * The server side protocol description may change on a per-transaction 140 * basis. Therefore we print this for each transaction and take an TSHttpTxn 141 * instead of a TSHttpSsn that the analogous get_client_protocol_description 142 * receives. 143 * 144 * @param[in] txnp The reference to the transaction. 145 * 146 * @return A JSON description of the server protocol stack for the 147 * transaction. 148 */ 149 std::string get_server_protocol_description(TSHttpTxn txnp); 150 151 /** Write the string to the session's dump file. 152 * 153 * @param[in] content The content to write to the file. 154 * 155 * @return TS_SUCCESS if the write is successfully scheduled with the AIO 156 * system, TS_ERROR otherwise. 157 */ 158 int write_to_disk(std::string_view content); 159 160 /** Write the transaction to the session's dump file. 161 * 162 * @param[in] content The transaction content to write to the file. 163 * 164 * @return TS_SUCCESS if the write is successfully scheduled with the AIO 165 * system, TS_ERROR otherwise. 166 */ 167 int write_transaction_to_disk(std::string_view content); 168 169 /** The HTTP version specified in the client-side protocol stack. 170 * 171 * The client protocol stack is obtained at session negotiation, before HTTP 172 * traffic is passed. So it may contain stack information if it was 173 * negotiated in the TLS handshake, as is often the case with HTTP/2, but it 174 * may not. This function returns whether the protocol stack contained HTTP 175 * information or not. 176 * 177 * @return The HTTP version in the client stack or empty string if it was not 178 * specified. 179 */ 180 std::string get_http_version_in_client_stack() const; 181 182 private: 183 /** Write the string to the session's dump file. 184 * 185 * This assumes that the caller acquired the required AIO lock. 186 * 187 * @param[in] content The content to write to the file. 188 * 189 * @return TS_SUCCESS if the write is successfully scheduled with the AIO 190 * system, TS_ERROR otherwise. 191 */ 192 int write_to_disk_no_lock(std::string_view content); 193 194 using get_protocol_stack_f = std::function<TSReturnCode(int, const char **, int *)>; 195 using get_tls_description_f = std::function<std::string()>; 196 using handle_http_version_f = std::function<void(std::string_view)>; 197 198 /** Create the protocol stack for a session. 199 * 200 * This function encapsulates the logic common between the client-side and 201 * server-side logic for populating a protocol stack. 202 * 203 * @param[in] get_protocol_stack The function to use to populate a protocol 204 * stack. 205 * 206 * @param[in] get_tls_node The function to use to populate the tls node. 207 * 208 * @param[in] handle_http_version A function that performs arbitrary logic 209 * given the HTTP/2 protocol version. 210 * 211 * @return The description of the protocol stack and True if the stack 212 * contained an HTTP description, false otherwise. 213 */ 214 std::string get_protocol_stack_helper(const get_protocol_stack_f &get_protocol_stack, const get_tls_description_f &get_tls_node, 215 const handle_http_version_f &handle_http_version); 216 217 /** Get the JSON string that describes the client session stack. 218 * 219 * @param[in] ssnp The reference to the client session. 220 * 221 * @return A description of the client protocol stack and True if the stack 222 * contained an HTTP description, false otherwise. 223 */ 224 std::string get_client_protocol_description(TSHttpSsn ssnp); 225 226 /** The handler callback for when async IO is done. Used for cleanup. */ 227 static int session_aio_handler(TSCont contp, TSEvent event, void *edata); 228 229 /** The handler callback for session events. */ 230 static int global_session_handler(TSCont contp, TSEvent event, void *edata); 231 }; 232 233 } // namespace traffic_dump 234