NCBI C++ ToolKit
ncbi_servicep.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_SERVICEP__H
2 #define CONNECT___NCBI_SERVICEP__H
3 
4 /* $Id: ncbi_servicep.h 101457 2023-12-15 16:56:06Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Anton Lavrentiev, Denis Vakatov
30  *
31  * File Description:
32  * Private API to define server iterator and related API.
33  *
34  */
35 
36 #include "ncbi_comm.h"
37 #include "ncbi_server_infop.h"
38 #include <connect/ncbi_service.h>
39 
40 
41 /* Order:
42  R>0 T>0 Active
43  R<0 T>0 Standby
44  R>0 T=0 Reserved
45 
46  R>0 T=INF Active+Suppressed
47  R<0 T=INF Standby+Suppressed
48  R<0 T=0 Reserved+Suppressed
49 
50  R=0 T>0 Down
51  R=0 T=INF Down+Suppressed
52 
53  R=0 T=0 Off (unseen)
54 */
55 
56 
57 /* SERV_IfSuppressed() can be applied to any of the SERV_Is*() macros below */
58 #define SERV_IfSuppressed(i) ( (i)->time == NCBI_TIME_INFINITE || \
59  (!(i)->time && (i)->rate < 0.0))
60 #define SERV_IsActive(i) ( (i)->time && (i)->rate > 0.0)
61 #define SERV_IsStandby(i) ( (i)->time && (i)->rate < 0.0)
62 #define SERV_IsReserved(i) ( !(i)->time && (i)->rate)
63 #define SERV_IsDown(i) ( !(i)->rate)
64 
65 /* Thus, SERV_IsUp() can be defined as follows */
66 #define SERV_IsUp(i) (SERV_IsActive(i) && !SERV_IfSuppressed(i))
67 
68 
69 #ifdef __cplusplus
70 extern "C" {
71 #endif
72 
73 
74 /* Table of iterator's "virtual functions"
75  */
76 typedef struct {
77  SSERV_Info* (*GetNextInfo)(SERV_ITER iter, HOST_INFO* host_info);
78  int/*bool*/ (*Feedback) (SERV_ITER iter, double rate, TNCBI_Time fine);
79  int/*bool*/ (*Update) (SERV_ITER iter, const char* text, int code);
80  void (*Reset) (SERV_ITER iter);
81  void (*Close) (SERV_ITER iter);
82  const char* mapper;
83 } SSERV_VTable;
84 
85 
86 /* Iterator structure, fields "packed" to consume minimal space.
87  */
88 struct SSERV_IterTag {
89  const char* name; /* requested service name, private storage */
90  double pref; /* preference [0..100]%% as a decimal fraction */
91  TNCBI_Time time; /* time of call */
92  unsigned int host; /* preferred host to select, network b.o. */
93  unsigned short port; /* preferred port to select, host b.o. */
94  TSERV_TypeOnly types; /* requested server types only, packed */
95  unsigned ismask:1; /* whether the name is to be treated as a mask */
96  unsigned ok_down:1; /* ..as taken.. */
97  unsigned ok_standby:1; /* ..from.. */
98  unsigned ok_reserved:1; /* ..types.. */
99  unsigned ok_suppressed:1; /* ..passed.. */
100  unsigned reverse_dns:1; /* ..to.. */
101  unsigned ok_private:1; /* ..SERV_*() calls.. */
102  unsigned external:1; /* whether this is an external request */
103  unsigned exact:1; /* service name is exact, defined by conf */
104  unsigned :23; /* reserved */
105  unsigned int localhost; /* local host address if known */
106  size_t o_skip; /* original number of servers passed in "skip" */
107  size_t n_skip; /* actual number of servers in the skip array */
108  size_t a_skip; /* number of allocated slots in the skip array */
109  SSERV_InfoCPtr* skip; /* servers to skip (always w/names) */
110  SSERV_InfoCPtr last; /* last server info taken out, points into skip*/
111  const char* arg; /* argument to match; the original pointer! */
112  const char* val; /* value to match; the original pointer! */
113  size_t arglen; /* NB: == 0 for the NULL "arg" pointer above */
114  size_t vallen; /* NB: == 0 for the NULL "val" pointer above */
115  void* data; /* private opaque data field of the mapper */
116  const SSERV_VTable* op; /* table of virtual functions */
117 };
118 
119 
120 /* Control whether to skip using registry/environment when opening iterators,
121  * and doing fast track lookups. Dangerous! Default is eOff.
122  */
124 
125 
126 /* Modified "fast track" routine for obtaining a server info in one-shot.
127  * Please see <connect/ncbi_service.h> for explanations [SERV_GetInfoEx()].
128  *
129  * CAUTION: Unlike the 'service' parameter, for performance reasons 'arg'
130  * and 'val' are not copied into the internal iterator structure
131  * but the original pointers to them get stored -- take this into
132  * account while dealing with dynamically allocated strings in the
133  * slow iterative version of the call below -- the pointers must
134  * remain valid as long as the iterator stays open (i.e. until
135  * SERV_Close() gets called).
136  *
137  * NOTE: Preference 0.0 does not prohibit the preferred_host to be selected;
138  * nor preference 100.0 ultimately opts for the preferred_host; rather,
139  * the preference is considered as an estimate for the selection
140  * probability when all other conditions for favoring the host are
141  * optimal, i.e. preference 0.0 actually means not to favor the preferred
142  * host at all, while 100.0 means to opt for that as much as possible.
143  *
144  * NOTE: Preference < 0.0 is a special value that means to latch the preferred
145  * host[:port] if the service exists out there, regardless of the load
146  * (but taking into account the server disposition [working/non-working]
147  * only: servers, which are down, don't get returned unless requested).
148  */
150 (const char* service, /* service name (may not be a mask here)*/
151  TSERV_Type types, /* mask of type(s) of servers requested */
152  unsigned int preferred_host,/* preferred host to use service on, nbo*/
153  unsigned short preferred_port,/* preferred port to use service on, hbo*/
154  double preference, /* [0,100] preference in %, or -1(latch)*/
155  const SConnNetInfo* net_info, /* for network dispatcher (0 to disable)*/
156  SSERV_InfoCPtr skip[], /* array of servers NOT to select */
157  size_t n_skip, /* number of servers in preceding array */
158  int/*bool*/ external, /* whether mapping is not local to NCBI */
159  const char* arg, /* environment variable name to search */
160  const char* val, /* environment variable value to match */
161  HOST_INFO* hinfo /* host information to return on match */
162  );
163 
164 
165 /* Same as the above but creates an iterator to get the servers one by one.
166  * CAUTION: Special requirement for "skip" infos in case of a wildcard
167  * service is that they _must_ be created having a name (perhaps, empty "")
168  * attached, like if done by SERV_ReadInfoEx() or SERV_CopyInfoEx().
169  */
171 (const char* service, /* service name (here: can be a mask!) */
173  unsigned int preferred_host,
174  unsigned short preferred_port,
175  double preference,
176  const SConnNetInfo* net_info,
177  SSERV_InfoCPtr skip[], /* must be "named" if service is a mask!*/
178  size_t n_skip,
179  int/*bool*/ external,
180  const char* arg,
181  const char* val
182  );
183 
184 
185 /* Return the service name, which the iterator is currently at.
186  */
187 extern NCBI_XCONNECT_EXPORT const char* SERV_CurrentName(SERV_ITER iter);
188 
189 
190 /* Same as SERV_Penalize() but can specify penalty hold time.
191  */
192 extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_PenalizeEx
193 (SERV_ITER iter, /* handle obtained via 'SERV_Open*' call*/
194  double fine, /* fine from range [0=min..100=max] (%%)*/
195  TNCBI_Time time /* for how long to keep the penalty, sec*/
196  );
197 
198 
199 /* Get a name of the underlying service mapper.
200  */
201 extern NCBI_XCONNECT_EXPORT const char* SERV_MapperName(SERV_ITER iter);
202 
203 
204 /* Private interface: update mapper information from the given text
205  * (<CR><LF> separated lines, usually as taken from HTTP header), and
206  * by optionally (if non-zero) using the HTTP error code provided.
207  */
208 int/*bool*/ SERV_Update
209 (SERV_ITER iter,
210  const char* text,
211  int code
212  );
213 
214 
215 /* Private interface: print and return an HTTP-compliant header portion
216  * (<CR><LF> separated lines, including the last line) out of information
217  * contained in the iterator; to be used in mapping requests to DISPD.
218  * "but_last" controls whether the currently taken info appears as the info
219  * to skip over (by the dispatcher) ["but_last"==0], or is just being used
220  * ["but_last"==1]. Return value must be free()'d.
221  */
222 char* SERV_Print
223 (SERV_ITER iter,
224  const SConnNetInfo* net_info, /* NB: only req'd for non-legacy fw conn req */
225  int/*bool*/ but_last
226  );
227 
228 
229 /* Private interface: get the final service name, using the
230  * service_CONN_SERVICE_NAME environment variable(s), then (if not found)
231  * registry section [service] and a key CONN_SERVICE_NAME. Return the
232  * resultant name (perhaps, an exact copy of "service" if no override name has
233  * been found in the environment/registry), which is to be 'free()'d by the
234  * caller when no longer needed. Return NULL on error.
235  * NOTE: This procedure can detect cyclic redefinitions, and is limited to a
236  * certain search depth.
237  */
238 char* SERV_ServiceName(const char* service);
239 
240 
241 /* Private interface: create SConnNetInfo for NULL, empty, or non-wildcard
242  * service name, without trying to resolve any service name substitution(s).
243  * @sa
244  * ConnNetInfo_Create, SERV_ServiceName, ConnNetInfo_GetValueInternal
245  */
246 SConnNetInfo* ConnNetInfo_CreateInternal(const char* service);
247 
248 
249 /* Private interface: Clone info without any dynamic fields (leave those 0).
250  * @sa
251  * ConnNetInfo_Clone, ConnNetInfo_CreateInternal
252  */
254 
255 
256 /* Private interface: same as ConnNetInfo_GetValue() for NULL, empty, or
257  * non-wildcard service name but without any service name substitution(s).
258  * Also, "param" is assumed to be in all-CAPS (plus underscores, if any).
259  * @sa
260  * ConnNetInfo_GetValue, SERV_ServiceName, ConnNetInfo_CreateInternal
261  */
262 const char* ConnNetInfo_GetValueInternal(const char* service,const char* param,
263  char* value, size_t value_size,
264  const char* def_value);
265 
266 
267 /* Private interface: same as ConnNetInfo_GetValue() for non-empty and
268  * non-wildcard service name but without any service name substitution(s),
269  * and without generic search fallback to "CONN_param" in the environment or
270  * "[CONN]param" in the registry.
271  * @sa
272  * ConnNetInfo_GetValue, SERV_ServiceName, ConnNetInfo_CreateInternal
273  */
274 const char* ConnNetInfo_GetValueService(const char* service, const char* param,
275  char* value, size_t value_size,
276  const char* def_value);
277 
278 
279 /* Private interface: drop any cached $http_proxy / $https_proxy */
281 
282 
283 /* Private interface: using the _DISABLE/_ENABLE key (e.g. CONN_LOCAL_ENABLE),
284  * return non-zero if set, zero if not. NB: "svc" may not be a mask. */
285 int/*bool*/ SERV_IsMapperConfiguredInternal(const char* svc, const char* key);
286 
287 
288 /* Private interface: manipulate a table of firewall ports */
289 void SERV_InitFirewallPorts(void);
290 
291 int/*bool*/ SERV_AddFirewallPort
292 (unsigned short port
293 );
294 
295 int/*bool*/ SERV_IsFirewallPort
296 (unsigned short port
297 );
298 
300 (char* buf,
301  size_t bufsize,
302  EFWMode mode
303 );
304 
305 
306 /* Return the global default */
308 
309 /* Private interface: same as public but service is not checked/substituted */
311 
312 
313 #ifdef __cplusplus
314 } /* extern "C" */
315 #endif
316 
317 #endif /* CONNECT___NCBI_SERVICEP__H */
static const struct type types[]
Definition: type.c:22
ESERV_Type
unsigned int TSERV_Type
Bitwise OR of ESERV_Type[Special].
Definition: ncbi_service.h:94
unsigned short TSERV_TypeOnly
Server type only, w/o specials.
Definition: ncbi_service.h:95
enum ENcbiSwitch ESwitch
Aux.
unsigned int TNCBI_Time
Definition: ncbi_types.h:145
EFWMode
#define NCBI_XCONNECT_EXPORT
char * buf
static void text(MDB_val *v)
Definition: mdb_dump.c:62
static MDB_envinfo info
Definition: mdb_load.c:37
mdb_mode_t mode
Definition: lmdb++.h:38
const struct ncbi::grid::netcache::search::fields::KEY key
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
ESERV_Type SERV_GetImplicitServerTypeInternal(const char *service)
SConnNetInfo * ConnNetInfo_CloneInternal(const SConnNetInfo *info)
SSERV_Info * SERV_GetInfoP(const char *service, TSERV_Type types, unsigned int preferred_host, unsigned short preferred_port, double preference, const SConnNetInfo *net_info, SSERV_InfoCPtr skip[], size_t n_skip, int external, const char *arg, const char *val, HOST_INFO *hinfo)
Definition: ncbi_service.c:903
const char * ConnNetInfo_GetValueService(const char *service, const char *param, char *value, size_t value_size, const char *def_value)
const char * ConnNetInfo_GetValueInternal(const char *service, const char *param, char *value, size_t value_size, const char *def_value)
int SERV_IsMapperConfiguredInternal(const char *svc, const char *key)
Definition: ncbi_service.c:247
void SERV_PrintFirewallPorts(char *buf, size_t bufsize, EFWMode mode)
char * SERV_ServiceName(const char *service)
Definition: ncbi_service.c:186
void SERV_InitFirewallPorts(void)
int SERV_Update(SERV_ITER iter, const char *text, int code)
const char * SERV_CurrentName(SERV_ITER iter)
Definition: ncbi_service.c:950
int SERV_IsFirewallPort(unsigned short port)
int SERV_PenalizeEx(SERV_ITER iter, double fine, TNCBI_Time time)
Definition: ncbi_service.c:957
SConnNetInfo * ConnNetInfo_CreateInternal(const char *service)
int SERV_AddFirewallPort(unsigned short port)
ESERV_Type SERV_GetImplicitServerTypeDefault(void)
char * SERV_Print(SERV_ITER iter, const SConnNetInfo *net_info, int but_last)
ESwitch SERV_DoFastOpens(ESwitch on)
SERV_ITER SERV_OpenP(const char *service, TSERV_Type types, unsigned int preferred_host, unsigned short preferred_port, double preference, const SConnNetInfo *net_info, SSERV_InfoCPtr skip[], size_t n_skip, int external, const char *arg, const char *val)
Definition: ncbi_service.c:837
void ConnNetInfo_ResetHttpProxyInternal(void)
const char * SERV_MapperName(SERV_ITER iter)
Definition: ncbi_service.c:943
static int bufsize
Definition: pcregrep.c:162
unsigned ok_suppressed
Definition: ncbi_servicep.h:99
unsigned external
unsigned ok_down
Definition: ncbi_servicep.h:96
unsigned ok_reserved
Definition: ncbi_servicep.h:98
unsigned short port
Definition: ncbi_servicep.h:93
const char * arg
const char * name
Definition: ncbi_servicep.h:89
unsigned exact
SSERV_InfoCPtr * skip
unsigned ismask
Definition: ncbi_servicep.h:95
unsigned int localhost
const char * val
const SSERV_VTable * op
unsigned int host
Definition: ncbi_servicep.h:92
unsigned ok_standby
Definition: ncbi_servicep.h:97
SSERV_InfoCPtr last
unsigned ok_private
unsigned reverse_dns
TSERV_TypeOnly types
Definition: ncbi_servicep.h:94
TNCBI_Time time
Definition: ncbi_servicep.h:91
const char * mapper
Definition: ncbi_servicep.h:82
Definition: inftrees.h:24
Modified on Fri Apr 12 17:18:05 2024 by modify_doxy.py rev. 669887