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

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_SERVER_INFO__H
2 #define CONNECT___NCBI_SERVER_INFO__H
3 
4 /* $Id: ncbi_server_info.h 93009 2021-02-27 06:03:52Z 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  * Authors: Anton Lavrentiev, Denis Vakatov
30  *
31  * File Description:
32  * @file ncbi_server_info.h
33  * NCBI server meta-address info
34  *
35  * Note that all server meta-addresses are allocated as single contiguous
36  * pieces of memory, which can be copied in whole with the use of
37  * 'SERV_SizeOfInfo' call. Dynamically allocated server infos can be freed
38  * with a direct call to 'free'.
39  *
40  * Assumptions on the fields: all fields in the server info come in host byte
41  * order except 'host', which comes in network byte order.
42  *
43  */
44 
45 #include <connect/ncbi_connutil.h>
46 #include <connect/ncbi_ipv6.h>
47 
48 
49 /** @addtogroup ServiceSupport
50  *
51  * @{
52  */
53 
54 #define SERV_DEFAULT_ALGO eSERV_Regular
55 #define SERV_MINIMAL_RATE 0.001
56 #define SERV_MAXIMAL_RATE 100000.0
57 #define SERV_MINIMAL_BONUS 0.01
58 #define SERV_MAXIMAL_BONUS 100.0
59 
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 
66 /* Server types
67  */
68 typedef enum {
69  fSERV_Ncbid = 0x01,
71  fSERV_HttpGet = 0x04,
75  fSERV_Dns = 0x20
77 
78 
79 /* Flag to specify an algorithm for selecting the most preferred server from
80  * a set of available servers (NB: binary properties of the enumerated values
81  * may be in use!).
82  */
83 typedef enum {
84  eSERV_Regular = 0, /* Server either tied up to lavg or static */
85  eSERV_Blast = 1 /* Server is tied up to an instant host load */
87 typedef unsigned char TSERV_Algo;
88 
89 
90 typedef enum {
91  fSERV_Stateful = 1, /* Server requires persistent connection */
92  fSERV_Secure = 2 /* Server requires secure connection */
94 typedef unsigned char TSERV_Mode;
95 
96 
97 typedef enum {
98  fSERV_Local = 1, /* Server accessible only for NCBI local clients*/
99  fSERV_Private = 2, /* Server accessible only by localhost clients */
100  fSERV_Interzone = 4, /* Server record spans LB zones within the site */
101  fSERV_ZoneMask = 0xF0 /* Local zone number for the server */
103 typedef unsigned char TSERV_Site;
104 
105 
106 /* Verbal representation of a server type (no internal spaces allowed)
107  */
108 extern NCBI_XCONNECT_EXPORT const char* SERV_TypeStr
110  );
111 
112 
113 /* Read server info type.
114  * If successful, assign "type" and return pointer to the position in the "str"
115  * immediately following the type tag. On error, return NULL.
116  */
117 extern NCBI_XCONNECT_EXPORT const char* SERV_ReadType
118 (const char* str,
120  );
121 
122 
123 /* Meta-addresses for various types of NCBI servers
124  */
125 typedef struct {
127 #define SERV_NCBID_ARGS(ui) ((char*)(ui) + (ui)->args)
129 
130 typedef struct {
131  char _pad; /* placeholder, must be same size as DNS's */
133 
134 typedef struct {
137 #define SERV_HTTP_PATH(ui) ((char*)(ui) + (ui)->path)
138 #define SERV_HTTP_ARGS(ui) ((char*)(ui) + (ui)->args)
140 
141 typedef struct {
142  ESERV_Type type; /* type of the original server */
144 
145 typedef struct {
146  unsigned char/*bool*/ name; /* name presence flag */
147 } SSERV_DnsInfo;
148 
149 
150 /* Generic NCBI server meta-address
151  */
152 typedef union {
158 } USERV_Info;
159 
160 typedef struct {
161  ESERV_Type type; /* type of server */
162  unsigned int host; /* host the server running on, network b.o. */
163  unsigned short port; /* port the server running on, host b.o. */
164  TSERV_Mode mode; /* connection mode (stateful, secure, etc) */
165  TSERV_Site site; /* site info (LSB: local, private; MSB: @#) */
166  TNCBI_Time time; /* relaxation period / expiration time */
167  double coef; /* bonus coefficient for server run locally */
168  double rate; /* rate of the server */
169  EMIME_Type mime_t; /* type, */
170  EMIME_SubType mime_s; /* subtype, */
171  EMIME_Encoding mime_e; /* and encoding for content-type */
172  TSERV_Algo algo; /* rate algorithm for the server */
173  TNCBI_IPv6Addr addr; /* IPv6 address (for host == INADDR_NONE(-1))*/
174  unsigned char vhost; /* extra (v)host namelen if non-zero (+'\0') */
175  unsigned short extra; /* extra data size if non-zero */
176  USERV_Info u; /* server type-specific data/params */
177 } SSERV_Info;
178 
179 
180 /* Constructors for the various types of NCBI server meta-addressesr45
181  */
183 (unsigned int host, /* network byte order */
184  unsigned short port, /* host byte order */
185  const char* args
186  );
187 
189 (unsigned int host, /* network byte order */
190  unsigned short port /* host byte order */
191  );
192 
194 (ESERV_Type type, /* verified, must be one of fSERV_Http* */
195  unsigned int host, /* network byte order */
196  unsigned short port, /* host byte order */
197  const char* path,
198  const char* args
199  );
200 
202 (unsigned int host, /* original server's host in net byte order */
203  unsigned short port, /* original server's port in host byte order */
204  ESERV_Type type /* type of original server, wrapped into */
205  );
206 
208 (unsigned int host /* network byte order, the only parameter */
209  );
210 
211 
212 /* Dump server info to a string.
213  * The server type goes first, and it is followed by a single space.
214  * The returned string is '\0'-terminated, and must be deallocated by 'free()'.
215  */
217 (const SSERV_Info* info
218  );
219 
220 
221 /* Server specification consists of the following:
222  * TYPE [host][:port] [server-specific_parameters] [tags]
223  *
224  * TYPE := { STANDALONE | NCBID | HTTP[{_GET|_POST}] | FIREWALL | DNS }
225  *
226  * Host must be specified as either an IP address (in dotted notation), as an
227  * IPv6 address (enclosed in square brackets), or as a host name (using domain
228  * notation if necessary). Port number must be preceded by a colon. Both host
229  * and port defaults to server-specific values if omitted. For null
230  * specification ":0" can be used.
231  *
232  * Server-specific parameters:
233  *
234  * STANDALONE servers: None
235  * Servers of this type do not take any arguments.
236  *
237  * NCBID servers: Arguments to CGI in addition to those specified by
238  * the application. Empty additional arguments should
239  * be denoted as '' (two single quotes, back to back)
240  * in order for the tags (that may follow) not be
241  * treated as the additional arguments. Note that the
242  * arguments must not contain any space characters.
243  *
244  * HTTP* servers: Path (required) and args (optional) in the form
245  * path[?args] (brackets denote the optional part).
246  * Note that no spaces are allowed within these
247  * parameters.
248  *
249  * FIREWALL servers: Servers of this type are converted real servers of
250  * the above types, when only accessible via FIREWALL
251  * mode of NCBI dispatcher. The purpose of this fake
252  * server type is just to let the client know that the
253  * service exists. Additional parameter is optional
254  * and if present, is the original type of the server
255  * before the conversion. Note that servers of this
256  * type cannot be configured in LBSMD.
257  *
258  * DNS servers: Services for DNS, DB load-balancing, and dynamic
259  * reverse-proxying (the ProxyPass directive of the
260  * Apache HTTP daemon) at the NCBI Web entry points.
261  * Never exposed to the outside.
262  *
263  * Tags may follow in no particular order but no more than one instance of each
264  * tag is allowed:
265  *
266  * Load average calculation algorithm for the server:
267  * A=R (Regular=default)
268  * A=B (Blast)
269  *
270  * Bonus coefficient:
271  * B=double [0.0 = default]
272  * specifies a multiplicative bonus given to a server run locally,
273  * when calculating its reachability rate.
274  * Special rules apply to negative/zero values:
275  * 0.0 means not to use the described rate increase at all (default
276  * rate calculation is used, which only slightly increases the rates
277  * of locally run servers).
278  * Negative value denotes that a locally run server should be taken
279  * in the first place, regardless of its rate, yet if that rate is as
280  * large as the percentage (expressed by the absolute value of this
281  * coefficient) of the average rate coefficient of all other servers
282  * for the same service. In other words, -5 instructs not to pick on
283  * the locally run server only if its rate is less than 5% of average
284  * status of the remaining servers for the same service.
285  *
286  * Content type indication:
287  * C=type/subtype [no default]
288  * specification of Content-Type (including encoding), which server
289  * accepts. The value of this flag gets added automatically to any
290  * HTTP packet sent to the server by SERVICE connector. However, in
291  * order to communicate, a client still has to know and generate the
292  * data type accepted by the server, i.e. a protocol, which server
293  * understands. This flag just helps ensure that all HTTP packets
294  * get proper content type, defined at service configuration. This
295  * tag is not allowed in the DNS type server specifications.
296  *
297  * (V)Host name:
298  * H=hostname (optional)
299  * specifies the host name to use when accessing the server. Can be
300  * implicitly set by server configuration if a hostname (instead of
301  * an IP) is provided as the connection point (the host:port pair).
302  * Value '' (two single quotes back-to-back) denotes no (v)host for
303  * cases when it might have been captured from the connection point.
304  *
305  * Local server:
306  * L={yes|no} [yes=default]
307  * Local servers are accessible only by local clients (from within
308  * the Intranet) or direct clients of LBSMD, and are not accessible
309  * by the outside users (e.g. via network dispatching).
310  *
311  * Private server:
312  * P=no (default)
313  * P=yes
314  * specifies whether the server is private for the host. Private
315  * server cannot be used from anywhere else but this host. When
316  * non-private (default), the server lacks 'P=no' in verbal
317  * representation resulted from SERV_WriteInfo(). This tag is not
318  * allowed in the DNS type server specifications.
319  *
320  * Reachability base rate:
321  * R=double [0.0 = default]
322  * specifies availability rate for the server, expressed as a
323  * floating point number with 0.0 meaning the server is down
324  * (unavailable) and 1000.0 meaning the server is up and running.
325  * Intermediate or higher values can be used to make the server less
326  * or more favorable for choosing by LBSM Daemon, as this coefficient
327  * is directly used as a multiplier in the load-average calculation
328  * for the entire family of servers for the same service. Normally,
329  * LBSMD keeps track of server reachability, and dynamically changes
330  * this rate to be the maximal specified when the server is up, and
331  * to be zero when the server is down. Note that negative values are
332  * reserved for LBSMD private use. To specify a server as inactive
333  * in LBSMD configuration file, one can use any negative number (note
334  * that value "0" in the config file means "default" and gets
335  * replaced with the value 1000.0). Values less than 0.01 define
336  * standby server entries, which are used by the clients only if
337  * there are no working entries with a higher initial rate available.
338  * Standby entries are not governed by the host load but are used up
339  * according to the values of rates in descending order (for
340  * same-rate entries, an entry is taken at random).
341  *
342  * Stateful server:
343  * S=no (default)
344  * S=yes
345  * indicates whether a server is stateful, which only allows context
346  * bearing, dedicated socket (stateful) connections. This tag is not
347  * allowed for HTTP* and DNS servers.
348  *
349  * Secure connection:
350  * $=no (default)
351  * $=yes
352  * indicates that connection to the server must be made over a secure
353  * protocol (HTTPS or SSL).
354  *
355  * Validity period:
356  * T=integer [0=default]
357  * specifies the time in seconds that this server entry is valid for
358  * without an update. (If equal to 0 then defaulted by the LBSM
359  * Daemon to some reasonable value.)
360  *
361  * Interzone server:
362  * X=no (default)
363  * X=yes
364  * indicates that the server definition can span zones within the
365  * current site (by default, a server info is local to a zone).
366  *
367  *
368  * Note that optional arguments can be omitted along with all preceding
369  * optional arguments; that is, the following 2 server specifications are both
370  * valid:
371  *
372  * NCBID ''
373  * and
374  * NCBID
375  *
376  * but they are not equal to the following specification:
377  *
378  * NCBID A=R
379  *
380  * because here 'A=R' is treated as an argument, not as a tag. To make the
381  * latter specification equivalent to the former two (since 'A=R' is the
382  * default tag), one has to use the following form:
383  *
384  * NCBID '' A=R
385  */
386 
387 
388 /* Read full server info (including type) from string "str" (e.g. composed by
389  * SERV_WriteInfo). Result can be later freed by 'free()'. If host is not
390  * provided in the server specification, info->host is set to 0; if port is
391  * missing, a type-specific default value is used.
392  */
394 (const char* info_str
395  );
396 
397 
398 /* Make (a free()'able) copy of a server info.
399  */
401 (const SSERV_Info* info
402  );
403 
404 
405 /* Return an actual size (in bytes) the server info occupies (to be used for
406  * copying info structures in whole).
407  */
409 (const SSERV_Info* info
410  );
411 
412 
413 /* Return non-zero('true') if two server infos are equal.
414  */
415 extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_EqualInfo
416 (const SSERV_Info* info1,
417  const SSERV_Info* info2
418  );
419 
420 
421 #ifdef __cplusplus
422 } /* extern "C" */
423 #endif
424 
425 
426 /* @} */
427 
428 #endif /* CONNECT___NCBI_SERVER_INFO__H */
static const char * str(char *buf, int n)
Definition: stats.c:84
SSERV_Info * SERV_CreateStandaloneInfo(unsigned int host, unsigned short port)
ESERV_Type
SSERV_HttpInfo http
SSERV_Info * SERV_CreateNcbidInfo(unsigned int host, unsigned short port, const char *args)
SSERV_Info * SERV_CopyInfo(const SSERV_Info *info)
TNCBI_Time time
EMIME_Encoding mime_e
EMIME_SubType mime_s
SSERV_Info * SERV_CreateDnsInfo(unsigned int host)
SSERV_DnsInfo dns
EMIME_Type mime_t
unsigned char TSERV_Mode
unsigned char name
SSERV_FirewallInfo firewall
SSERV_Info * SERV_ReadInfo(const char *info_str)
size_t SERV_SizeOfInfo(const SSERV_Info *info)
ESERV_Mode
SSERV_NcbidInfo ncbid
TSERV_Site site
const char * SERV_ReadType(const char *str, ESERV_Type *type)
TSERV_Mode mode
TNCBI_IPv6Addr addr
unsigned char vhost
unsigned char TSERV_Site
const char * SERV_TypeStr(ESERV_Type type)
SSERV_StandaloneInfo standalone
unsigned char TSERV_Algo
SSERV_Info * SERV_CreateHttpInfo(ESERV_Type type, unsigned int host, unsigned short port, const char *path, const char *args)
TSERV_Algo algo
char * SERV_WriteInfo(const SSERV_Info *info)
SSERV_Info * SERV_CreateFirewallInfo(unsigned int host, unsigned short port, ESERV_Type type)
ESERV_Algo
unsigned int host
ESERV_Site
unsigned short extra
unsigned short port
USERV_Info u
int SERV_EqualInfo(const SSERV_Info *info1, const SSERV_Info *info2)
ESERV_Type type
@ fSERV_Firewall
@ fSERV_Http
@ fSERV_HttpPost
@ fSERV_Standalone
@ fSERV_HttpGet
@ fSERV_Dns
@ fSERV_Ncbid
@ fSERV_Secure
@ fSERV_Stateful
@ eSERV_Blast
@ eSERV_Regular
@ fSERV_Local
@ fSERV_Interzone
@ fSERV_Private
@ fSERV_ZoneMask
unsigned int TNCBI_Time
Definition: ncbi_types.h:145
unsigned int TNCBI_Size
Fixed-size analogs of size_t and time_t (mainly for IPC)
Definition: ncbi_types.h:144
EMIME_Type
EMIME_SubType
EMIME_Encoding
#define NCBI_XCONNECT_EXPORT
static MDB_envinfo info
Definition: mdb_load.c:37
Definition: type.c:6
Modified on Mon Apr 22 04:01:01 2024 by modify_doxy.py rev. 669887