1 /** @file 2 3 A brief file description 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 /* 25 * Interfaces in this header file are experimental, undocumented and 26 * are subject to change even across minor releases of Traffic Server. 27 * None of the interfaces in this file are committed to be stable 28 * unless they are migrated to ts/ts.h If you require stable APIs to 29 * Traffic Server, DO NOT USE anything in this file. 30 */ 31 32 #pragma once 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif /* __cplusplus */ 37 38 typedef enum { 39 TS_FETCH_EVENT_EXT_HEAD_READY = -1, 40 TS_FETCH_EVENT_EXT_HEAD_DONE = -2, 41 TS_FETCH_EVENT_EXT_BODY_READY = -3, 42 TS_FETCH_EVENT_EXT_BODY_DONE = -4 43 } TSFetchEventExt; 44 45 typedef enum { 46 TS_FETCH_FLAGS_NONE = 0, // do nothing 47 TS_FETCH_FLAGS_STREAM = 1 << 1, // enable stream IO 48 TS_FETCH_FLAGS_DECHUNK = 1 << 2, // dechunk body content 49 TS_FETCH_FLAGS_NEWLOCK = 1 << 3, // allocate new lock for fetch sm 50 TS_FETCH_FLAGS_NOT_INTERNAL_REQUEST = 1 << 4 // Allow this fetch to be created as a non-internal request. 51 } TSFetchFlags; 52 53 /* Forward declaration of in_addr, any user of these APIs should probably 54 include net/netinet.h or whatever is appropriate on the platform. */ 55 struct in_addr; 56 57 /* Cache APIs that are not yet fully supported and/or frozen nor complete. */ 58 tsapi TSReturnCode TSCacheBufferInfoGet(TSCacheTxn txnp, uint64_t *length, uint64_t *offset); 59 60 tsapi TSCacheHttpInfo TSCacheHttpInfoCreate(); 61 tsapi void TSCacheHttpInfoReqGet(TSCacheHttpInfo infop, TSMBuffer *bufp, TSMLoc *obj); 62 tsapi void TSCacheHttpInfoRespGet(TSCacheHttpInfo infop, TSMBuffer *bufp, TSMLoc *obj); 63 tsapi void TSCacheHttpInfoReqSet(TSCacheHttpInfo infop, TSMBuffer bufp, TSMLoc obj); 64 tsapi void TSCacheHttpInfoRespSet(TSCacheHttpInfo infop, TSMBuffer bufp, TSMLoc obj); 65 tsapi void TSCacheHttpInfoKeySet(TSCacheHttpInfo infop, TSCacheKey key); 66 tsapi void TSCacheHttpInfoSizeSet(TSCacheHttpInfo infop, int64_t size); 67 tsapi int TSCacheHttpInfoVector(TSCacheHttpInfo infop, void *data, int length); 68 tsapi time_t TSCacheHttpInfoReqSentTimeGet(TSCacheHttpInfo infop); 69 tsapi time_t TSCacheHttpInfoRespReceivedTimeGet(TSCacheHttpInfo infop); 70 int64_t TSCacheHttpInfoSizeGet(TSCacheHttpInfo infop); 71 72 /* Do not edit these apis, used internally */ 73 tsapi int TSMimeHdrFieldEqual(TSMBuffer bufp, TSMLoc hdr_obj, TSMLoc field1, TSMLoc field2); 74 tsapi TSReturnCode TSHttpTxnHookRegisteredFor(TSHttpTxn txnp, TSHttpHookID id, TSEventFunc funcp); 75 76 /* Various HTTP "control" modes */ 77 typedef enum { 78 TS_HTTP_CNTL_GET_LOGGING_MODE, 79 TS_HTTP_CNTL_SET_LOGGING_MODE, 80 TS_HTTP_CNTL_GET_INTERCEPT_RETRY_MODE, 81 TS_HTTP_CNTL_SET_INTERCEPT_RETRY_MODE 82 } TSHttpCntlType; 83 84 #define TS_HTTP_CNTL_OFF (void *)0 85 #define TS_HTTP_CNTL_ON (void *)1 86 /* usage: 87 void *onoff = 0; 88 TSHttpTxnCntl(.., TS_HTTP_CNTL_GET_LOGGING_MODE, &onoff); 89 if (onoff == TS_HTTP_CNTL_ON) .... 90 */ 91 tsapi TSReturnCode TSHttpTxnCntl(TSHttpTxn txnp, TSHttpCntlType cntl, void *data); 92 93 /* Protocols APIs */ 94 tsapi void TSVConnCacheHttpInfoSet(TSVConn connp, TSCacheHttpInfo infop); 95 96 /* The rest is from the old "froze" private API include, we should consider 97 moving some of these over to ts/ts.h as well. TODO */ 98 99 /**************************************************************************** 100 * Test if cache ready to accept request for a specific type of data 101 ****************************************************************************/ 102 tsapi TSReturnCode TSCacheDataTypeReady(TSCacheDataType type, int *is_ready); 103 104 /**************************************************************************** 105 * When reenabling a txn in error, keep the connection open in case 106 * of keepalive. 107 ****************************************************************************/ 108 tsapi void TSHttpTxnClientKeepaliveSet(TSHttpTxn txnp, int set); 109 110 /**************************************************************************** 111 * Allow to set the body of a POST request. 112 ****************************************************************************/ 113 tsapi void TSHttpTxnServerRequestBodySet(TSHttpTxn txnp, char *buf, int64_t buflength); 114 115 /* ===== High Resolution Time ===== */ 116 #define TS_HRTIME_FOREVER (10 * TS_HRTIME_DECADE) 117 #define TS_HRTIME_DECADE (10 * TS_HRTIME_YEAR) 118 #define TS_HRTIME_YEAR (365 * TS_HRTIME_DAY + TS_HRTIME_DAY / 4) 119 #define TS_HRTIME_WEEK (7 * TS_HRTIME_DAY) 120 #define TS_HRTIME_DAY (24 * TS_HRTIME_HOUR) 121 #define TS_HRTIME_HOUR (60 * TS_HRTIME_MINUTE) 122 #define TS_HRTIME_MINUTE (60 * TS_HRTIME_SECOND) 123 #define TS_HRTIME_SECOND (1000 * TS_HRTIME_MSECOND) 124 #define TS_HRTIME_MSECOND (1000 * TS_HRTIME_USECOND) 125 #define TS_HRTIME_USECOND (1000 * TS_HRTIME_NSECOND) 126 #define TS_HRTIME_NSECOND (1LL) 127 128 #define TS_HRTIME_APPROX_SECONDS(_x) ((_x) >> 30) /* off by 7.3% */ 129 #define TS_HRTIME_APPROX_FACTOR (((float)(1 << 30)) / (((float)HRTIME_SECOND))) 130 131 /* 132 //////////////////////////////////////////////////////////////////// 133 // 134 // Map from units to ts_hrtime values 135 // 136 //////////////////////////////////////////////////////////////////// 137 */ 138 #define TS_HRTIME_YEARS(_x) ((_x)*TS_HRTIME_YEAR) 139 #define TS_HRTIME_WEEKS(_x) ((_x)*TS_HRTIME_WEEK) 140 #define TS_HRTIME_DAYS(_x) ((_x)*TS_HRTIME_DAY) 141 #define TS_HRTIME_HOURS(_x) ((_x)*TS_HRTIME_HOUR) 142 #define TS_HRTIME_MINUTES(_x) ((_x)*TS_HRTIME_MINUTE) 143 #define TS_HRTIME_SECONDS(_x) ((_x)*TS_HRTIME_SECOND) 144 #define TS_HRTIME_MSECONDS(_x) ((_x)*TS_HRTIME_MSECOND) 145 #define TS_HRTIME_USECONDS(_x) ((_x)*TS_HRTIME_USECOND) 146 #define TS_HRTIME_NSECONDS(_x) ((_x)*TS_HRTIME_NSECOND) 147 148 tsapi TSReturnCode TSHttpTxnCachedRespTimeGet(TSHttpTxn txnp, time_t *resp_time); 149 150 /* ===== Cache ===== */ 151 tsapi TSReturnCode TSCacheKeyDataTypeSet(TSCacheKey key, TSCacheDataType type); 152 153 /* ===== Utility ===== */ 154 /**************************************************************************** 155 * Create a random number 156 * Return random integer between <X> and <Y> 157 ****************************************************************************/ 158 tsapi unsigned int TSrandom(void); 159 160 /**************************************************************************** 161 * Create a random double 162 * Return random double between <X> and <Y> 163 ****************************************************************************/ 164 tsapi double TSdrandom(void); 165 166 /**************************************************************************** 167 * Return Hi-resolution current time. (int64_t) 168 ****************************************************************************/ 169 tsapi TSHRTime TShrtime(void); 170 171 /* ===== CacheHttpInfo ===== */ 172 173 tsapi TSCacheHttpInfo TSCacheHttpInfoCopy(TSCacheHttpInfo infop); 174 tsapi void TSCacheHttpInfoReqGet(TSCacheHttpInfo infop, TSMBuffer *bufp, TSMLoc *offset); 175 tsapi void TSCacheHttpInfoRespGet(TSCacheHttpInfo infop, TSMBuffer *bufp, TSMLoc *offset); 176 tsapi void TSCacheHttpInfoDestroy(TSCacheHttpInfo infop); 177 178 /* Get Arbitrary Txn info such as cache lookup details etc as defined in TSHttpTxnInfoKey */ 179 /** 180 Return the particular txn info requested. 181 182 @param txnp the transaction pointer 183 @param key the requested txn info. 184 @param TSMgmtInt a pointer to a integer where the return value is stored 185 186 @return @c TS_SUCCESS if the requested info is supported, TS_ERROR otherwise 187 188 */ 189 tsapi TSReturnCode TSHttpTxnInfoIntGet(TSHttpTxn txnp, TSHttpTxnInfoKey key, TSMgmtInt *value); 190 191 /**************************************************************************** 192 * TSHttpTxnCacheLookupCountGet 193 * Return: TS_SUCCESS/TS_ERROR 194 ****************************************************************************/ 195 tsapi TSReturnCode TSHttpTxnCacheLookupCountGet(TSHttpTxn txnp, int *lookup_count); 196 tsapi TSReturnCode TSHttpTxnServerRespIgnore(TSHttpTxn txnp); 197 tsapi TSReturnCode TSHttpTxnShutDown(TSHttpTxn txnp, TSEvent event); 198 tsapi TSReturnCode TSHttpTxnCloseAfterResponse(TSHttpTxn txnp, int should_close); 199 200 /** Do another cache lookup with a different cache key. 201 * 202 * @param txnp Transaction. 203 * @param url URL to use for cache key. 204 * @param length Length of the string in @a url 205 * 206 * @return @c TS_SUCCESS on success, @c TS_ERROR if the @a txnp is invalid or the @a url is 207 * not a valid URL. 208 * 209 * If @a length is negative, @c strlen will be used to determine the length of @a url. 210 * 211 * @a url must be syntactically a URL, but otherwise it is just a string and does not need to 212 * be retrievable. 213 * 214 * This can only be called in a @c TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK callback. To set the cache 215 * key for the first lookup, use @c TSCacheUrlSet. 216 * 217 * @see TSCacheUrlSet 218 */ 219 tsapi TSReturnCode TSHttpTxnRedoCacheLookup(TSHttpTxn txnp, const char *url, int length); 220 221 /**************************************************************************** 222 * ?? 223 * Return ?? 224 ****************************************************************************/ 225 tsapi int TSHttpTxnClientReqIsServerStyle(TSHttpTxn txnp); 226 227 /**************************************************************************** 228 * ?? 229 * Return ?? 230 ****************************************************************************/ 231 tsapi void TSHttpTxnOverwriteExpireTime(TSHttpTxn txnp, time_t expire_time); 232 233 /**************************************************************************** 234 * ?? 235 * Return ?? 236 ****************************************************************************/ 237 tsapi TSReturnCode TSHttpTxnUpdateCachedObject(TSHttpTxn txnp); 238 239 /**************************************************************************** 240 * ?? 241 * TODO: This returns a LookingUp_t value, we need to SDK'ify it. 242 ****************************************************************************/ 243 tsapi int TSHttpTxnLookingUpTypeGet(TSHttpTxn txnp); 244 245 /* ip addr parsing */ 246 tsapi TSReturnCode TSIpStringToAddr(const char *str, size_t str_len, struct sockaddr *addr); 247 248 /** 249 Attempt to attach the contp continuation to sockets that have already been 250 opened by the traffic manager and defined as belonging to plugins (based on 251 records.config configuration). If a connection is successfully accepted, 252 the TS_EVENT_NET_ACCEPT is delivered to the continuation. The event 253 data will be a valid TSVConn bound to the accepted connection. 254 In order to configure such a socket, add the "plugin" keyword to a port 255 in proxy.config.http.server_ports like "8082:plugin" 256 Transparency/IP settings can also be defined, but a port cannot have 257 both the "ssl" or "plugin" keywords configured. 258 259 Need to update records.config comments on proxy.config.http.server_ports 260 when this option is promoted from experimental. 261 */ 262 tsapi TSReturnCode TSPluginDescriptorAccept(TSCont contp); 263 264 /** 265 Opens a network connection to the host specified by the 'to' sockaddr 266 spoofing the client addr to equal the 'from' sockaddr. 267 If the connection is successfully opened, contp 268 is called back with the event TS_EVENT_NET_CONNECT and the new 269 network vconnection will be passed in the event data parameter. 270 If the connection is not successful, contp is called back with 271 the event TS_EVENT_NET_CONNECT_FAILED. 272 273 Note: It is possible to receive TS_EVENT_NET_CONNECT 274 even if the connection failed, because of the implementation of 275 network sockets in the underlying operating system. There is an 276 exception: if a plugin tries to open a connection to a port on 277 its own host machine, then TS_EVENT_NET_CONNECT is sent only 278 if the connection is successfully opened. In general, however, 279 your plugin needs to look for an TS_EVENT_VCONN_WRITE_READY to 280 be sure that the connection is successfully opened. 281 282 @return TSAction which allows you to check if the connection is complete, 283 or cancel the attempt to connect. 284 285 */ 286 tsapi TSAction TSNetConnectTransparent( 287 TSCont contp, /**< continuation that is called back when the attempted net connection either succeeds or fails. */ 288 struct sockaddr const *from, /**< Address to spoof as connection origin */ 289 struct sockaddr const *to /**< Address to which to connect. */ 290 ); 291 292 /* ===== Matcher Utils ===== */ 293 #define TS_MATCHER_LINE_INVALID 0 294 typedef struct tsapi_matcheline *TSMatcherLine; 295 296 /**************************************************************************** 297 * ?? 298 * Return 299 ****************************************************************************/ 300 tsapi char *TSMatcherReadIntoBuffer(char *file_name, int *file_len); 301 302 /**************************************************************************** 303 * ?? 304 * Return 305 ****************************************************************************/ 306 tsapi char *TSMatcherTokLine(char *buffer, char **last); 307 308 /**************************************************************************** 309 * ?? 310 * Return 311 ****************************************************************************/ 312 tsapi char *TSMatcherExtractIPRange(char *match_str, uint32_t *addr1, uint32_t *addr2); 313 314 /**************************************************************************** 315 * ?? 316 * Return 317 ****************************************************************************/ 318 tsapi TSMatcherLine TSMatcherLineCreate(); 319 320 /**************************************************************************** 321 * ?? 322 * Return 323 ****************************************************************************/ 324 tsapi void TSMatcherLineDestroy(TSMatcherLine ml); 325 326 /**************************************************************************** 327 * ?? 328 * Return 329 ****************************************************************************/ 330 tsapi const char *TSMatcherParseSrcIPConfigLine(char *line, TSMatcherLine ml); 331 332 /**************************************************************************** 333 * ?? 334 * Return 335 ****************************************************************************/ 336 tsapi char *TSMatcherLineName(TSMatcherLine ml, int element); 337 338 /**************************************************************************** 339 * ?? 340 * Return 341 ****************************************************************************/ 342 tsapi char *TSMatcherLineValue(TSMatcherLine ml, int element); 343 344 /**************************************************************************** 345 * Set a records.config integer variable 346 ****************************************************************************/ 347 tsapi TSReturnCode TSMgmtConfigIntSet(const char *var_name, TSMgmtInt value); 348 349 tsapi TSReturnCode TSMgmtConfigFileAdd(const char *parent, const char *fileName); 350 /* ---------------------------------------------------------------------- 351 * Interfaces used by Wireless group 352 * ---------------------------------------------------------------------- */ 353 354 #define TS_NET_EVENT_DATAGRAM_READ_COMPLETE TS_EVENT_INTERNAL_206 355 #define TS_NET_EVENT_DATAGRAM_READ_ERROR TS_EVENT_INTERNAL_207 356 #define TS_NET_EVENT_DATAGRAM_WRITE_COMPLETE TS_EVENT_INTERNAL_208 357 #define TS_NET_EVENT_DATAGRAM_WRITE_ERROR TS_EVENT_INTERNAL_209 358 #define TS_NET_EVENT_DATAGRAM_READ_READY TS_EVENT_INTERNAL_210 359 #define TS_NET_EVENT_DATAGRAM_OPEN TS_EVENT_INTERNAL_211 360 #define TS_NET_EVENT_DATAGRAM_ERROR TS_EVENT_INTERNAL_212 361 362 /** 363 * Extended FetchSM's AIPs 364 */ 365 366 /* 367 * Create FetchSM, this API will enable stream IO automatically. 368 * 369 * @param contp: continuation to be callbacked. 370 * @param method: request method. 371 * @param url: scheme://host[:port]/path. 372 * @param version: client http version, eg: "HTTP/1.1". 373 * @param client_addr: client addr sent to log. 374 * @param flags: can be bitwise OR of several TSFetchFlags. 375 * 376 * return TSFetchSM which should be destroyed by TSFetchDestroy(). 377 */ 378 tsapi TSFetchSM TSFetchCreate(TSCont contp, const char *method, const char *url, const char *version, 379 struct sockaddr const *client_addr, int flags); 380 381 /* 382 * Set fetch flags to FetchSM Context 383 * 384 * @param fetch_sm: returned value of TSFetchCreate(). 385 * @param flags: can be bitwise OR of several TSFetchFlags. 386 * 387 * return void 388 */ 389 tsapi void TSFetchFlagSet(TSFetchSM fetch_sm, int flags); 390 391 /* 392 * Create FetchSM, this API will enable stream IO automatically. 393 * 394 * @param fetch_sm: returned value of TSFetchCreate(). 395 * @param name: name of header. 396 * @param name_len: len of name. 397 * @param value: value of header. 398 * @param name_len: len of value. 399 * 400 * return TSFetchSM which should be destroyed by TSFetchDestroy(). 401 */ 402 tsapi void TSFetchHeaderAdd(TSFetchSM fetch_sm, const char *name, int name_len, const char *value, int value_len); 403 404 /* 405 * Write data to FetchSM 406 * 407 * @param fetch_sm: returned value of TSFetchCreate(). 408 * @param data/len: data to be written to fetch sm. 409 */ 410 tsapi void TSFetchWriteData(TSFetchSM fetch_sm, const void *data, size_t len); 411 412 /* 413 * Read up to *len* bytes from FetchSM into *buf*. 414 * 415 * @param fetch_sm: returned value of TSFetchCreate(). 416 * @param buf/len: buffer to contain data from fetch sm. 417 */ 418 tsapi ssize_t TSFetchReadData(TSFetchSM fetch_sm, void *buf, size_t len); 419 420 /* 421 * Launch FetchSM to do http request, before calling this API, 422 * you should append http request header into fetch sm through 423 * TSFetchWriteData() API 424 * 425 * @param fetch_sm: comes from returned value of TSFetchCreate(). 426 */ 427 tsapi void TSFetchLaunch(TSFetchSM fetch_sm); 428 429 /* 430 * Destroy FetchSM 431 * 432 * @param fetch_sm: returned value of TSFetchCreate(). 433 */ 434 tsapi void TSFetchDestroy(TSFetchSM fetch_sm); 435 436 /* 437 * Set user-defined data in FetchSM 438 */ 439 tsapi void TSFetchUserDataSet(TSFetchSM fetch_sm, void *data); 440 441 /* 442 * Get user-defined data in FetchSM 443 */ 444 tsapi void *TSFetchUserDataGet(TSFetchSM fetch_sm); 445 446 /* 447 * Get client response hdr mbuffer 448 */ 449 tsapi TSMBuffer TSFetchRespHdrMBufGet(TSFetchSM fetch_sm); 450 451 /* 452 * Get client response hdr mloc 453 */ 454 tsapi TSMLoc TSFetchRespHdrMLocGet(TSFetchSM fetch_sm); 455 456 /* 457 * Parse a MIME header date string. 458 */ 459 tsapi time_t TSMimeParseDate(char const *const value_str, int const value_len); 460 461 /* 462 * Print as a MIME header date string. 463 */ 464 tsapi TSReturnCode TSMimeFormatDate(time_t const value_time, char *const value_str, int *const value_len); 465 466 #ifdef __cplusplus 467 } 468 #endif /* __cplusplus */ 469