1 /* $NetBSD: scache.h,v 1.1.1.1 2009/06/23 10:08:48 tron Exp $ */ 2 3 #ifndef _SCACHE_H_INCLUDED_ 4 #define _SCACHE_H_INCLUDED_ 5 6 /*++ 7 /* NAME 8 /* scache 3h 9 /* SUMMARY 10 /* generic session cache API 11 /* SYNOPSIS 12 /* #include <scache.h> 13 /* DESCRIPTION 14 /* .nf 15 16 /* 17 * Utility library. 18 */ 19 #include <vstring.h> 20 21 typedef struct SCACHE SCACHE; 22 typedef struct SCACHE_SIZE SCACHE_SIZE; 23 24 /* 25 * In order to cache a session, we specify: 26 * 27 * - TTL for this session. 28 * 29 * - File descriptor. 30 * 31 * - Transport name and physical endpoint. The transport name must be included, 32 * because fall-back destinations can be transport-dependent, and routing 33 * for a given destination may be context dependent. 34 * 35 * In the case of SMTP, the physical endpoint is the numerical IP address and 36 * TCP port. 37 * 38 * - Application-specific endpoint properties. 39 * 40 * In the case of SMTP, the properties specify the ESMTP features advertised by 41 * the server. 42 * 43 * Note: with message delivery transports that have only one endpoint per 44 * logical destination, the above is the only information that needs to be 45 * maintained in a connection cache. 46 */ 47 typedef void (*SCACHE_SAVE_ENDP_FN) (SCACHE *, int, const char *, const char *, int); 48 typedef int (*SCACHE_FIND_ENDP_FN) (SCACHE *, const char *, VSTRING *); 49 50 /* 51 * The following information is stored in order to make a binding from 52 * logical destination to physical destination. One logical destination can 53 * have multiple physical destinations (and one physical destination can 54 * have multiple sessions). 55 * 56 * - TTL for this binding. 57 * 58 * - Transport name and logical destination. 59 * 60 * In the case of SMTP: the next-hop (NOT: fall-back) destination domain and 61 * destination network port. It is not useful to create a link for an 62 * address literal (but it is not harmful either: it just wastes a few 63 * bits). This information specifies the destination domain in [] if no MX 64 * lookup is done. 65 * 66 * - Application-specific properties. 67 * 68 * In case the of SMTP, the properties specify a) whether a physical endpoint 69 * is best mx host with respect to a logical or fall-back destination (this 70 * information is needed by the loop detection code in smtp_proto.c). 71 * 72 * - Transport name and physical endpoint (see above). 73 * 74 * Note 1: there is no need to store the binding's MX preference or equivalent 75 * with respect to the logical destination; a client should store only the 76 * first successful session for a given delivery request (otherwise the 77 * client would keep talking to a less preferred server after the cached 78 * connection for a more preferred server expires). After a failed delivery, 79 * the client should not attempt to cache follow-up sessions with less 80 * preferred endpoints under the same logical destination. 81 * 82 * Note 2: logical to physical bindings exist independently from cached 83 * sessions. The two types of information have independent TTLs; creation 84 * and destruction proceed independently. Thus, a logical to physical 85 * binding can refer to an endpoint for which all cached connections are 86 * occupied or expired. 87 */ 88 typedef void (*SCACHE_SAVE_DEST_FN) (SCACHE *, int, const char *, const char *, const char *); 89 typedef int (*SCACHE_FIND_DEST_FN) (SCACHE *, const char *, VSTRING *, VSTRING *); 90 91 /* 92 * Session cache statistics. These are the actual numbers at a specific 93 * point in time. 94 */ 95 struct SCACHE_SIZE { 96 int dest_count; /* Nr of destination names */ 97 int endp_count; /* Nr of endpoint adresses */ 98 int sess_count; /* Nr of cached sessions */ 99 }; 100 101 /* 102 * Generic session cache object. Actual session cache objects are derived 103 * types with some additional, cache dependent, private information. 104 */ 105 struct SCACHE { 106 SCACHE_SAVE_ENDP_FN save_endp; 107 SCACHE_FIND_ENDP_FN find_endp; 108 SCACHE_SAVE_DEST_FN save_dest; 109 SCACHE_FIND_DEST_FN find_dest; 110 void (*size) (struct SCACHE *, SCACHE_SIZE *); 111 void (*free) (struct SCACHE *); 112 }; 113 114 extern SCACHE *scache_single_create(void); 115 extern SCACHE *scache_clnt_create(const char *, int, int, int); 116 extern SCACHE *scache_multi_create(void); 117 118 #define scache_save_endp(scache, ttl, endp_label, endp_prop, fd) \ 119 (scache)->save_endp((scache), (ttl), (endp_label), (endp_prop), (fd)) 120 #define scache_find_endp(scache, endp_label, endp_prop) \ 121 (scache)->find_endp((scache), (endp_label), (endp_prop)) 122 #define scache_save_dest(scache, ttl, dest_label, dest_prop, endp_label) \ 123 (scache)->save_dest((scache), (ttl), (dest_label), (dest_prop), (endp_label)) 124 #define scache_find_dest(scache, dest_label, dest_prop, endp_prop) \ 125 (scache)->find_dest((scache), (dest_label), (dest_prop), (endp_prop)) 126 #define scache_size(scache, stats) (scache)->size((scache), (stats)) 127 #define scache_free(scache) (scache)->free(scache) 128 129 /* 130 * Cache types. 131 */ 132 #define SCACHE_TYPE_SINGLE 1 /* single-instance cache */ 133 #define SCACHE_TYPE_CLIENT 2 /* session cache client */ 134 #define SCACHE_TYPE_MULTI 3 /* multi-instance cache */ 135 136 /* 137 * Client-server protocol. 138 */ 139 #define SCACHE_REQ_FIND_ENDP "find_endp" 140 #define SCACHE_REQ_SAVE_ENDP "save_endp" 141 #define SCACHE_REQ_FIND_DEST "find_dest" 142 #define SCACHE_REQ_SAVE_DEST "save_dest" 143 144 /* 145 * Session cache server status codes. 146 */ 147 #define SCACHE_STAT_OK 0 /* request completed successfully */ 148 #define SCACHE_STAT_BAD 1 /* malformed request */ 149 #define SCACHE_STAT_FAIL 2 /* request completed unsuccessfully */ 150 151 /* LICENSE 152 /* .ad 153 /* .fi 154 /* The Secure Mailer license must be distributed with this software. 155 /* AUTHOR(S) 156 /* Wietse Venema 157 /* IBM T.J. Watson Research 158 /* P.O. Box 704 159 /* Yorktown Heights, NY 10598, USA 160 /*--*/ 161 162 #endif 163