summaryrefslogtreecommitdiffstats
path: root/src/global/scache.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:18:56 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:18:56 +0000
commitb7c15c31519dc44c1f691e0466badd556ffe9423 (patch)
treef944572f288bab482a615e09af627d9a2b6727d8 /src/global/scache.h
parentInitial commit. (diff)
downloadpostfix-b7c15c31519dc44c1f691e0466badd556ffe9423.tar.xz
postfix-b7c15c31519dc44c1f691e0466badd556ffe9423.zip
Adding upstream version 3.7.10.upstream/3.7.10
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/global/scache.h')
-rw-r--r--src/global/scache.h165
1 files changed, 165 insertions, 0 deletions
diff --git a/src/global/scache.h b/src/global/scache.h
new file mode 100644
index 0000000..a46362a
--- /dev/null
+++ b/src/global/scache.h
@@ -0,0 +1,165 @@
+#ifndef _SCACHE_H_INCLUDED_
+#define _SCACHE_H_INCLUDED_
+
+/*++
+/* NAME
+/* scache 3h
+/* SUMMARY
+/* generic session cache API
+/* SYNOPSIS
+/* #include <scache.h>
+/* DESCRIPTION
+/* .nf
+
+ /*
+ * Utility library.
+ */
+#include <vstring.h>
+
+typedef struct SCACHE SCACHE;
+typedef struct SCACHE_SIZE SCACHE_SIZE;
+
+ /*
+ * In order to cache a session, we specify:
+ *
+ * - TTL for this session.
+ *
+ * - File descriptor.
+ *
+ * - Transport name and physical endpoint. The transport name must be included,
+ * because fall-back destinations can be transport-dependent, and routing
+ * for a given destination may be context dependent.
+ *
+ * In the case of SMTP, the physical endpoint is the numerical IP address and
+ * TCP port.
+ *
+ * - Application-specific endpoint properties.
+ *
+ * In the case of SMTP, the properties specify the ESMTP features advertised by
+ * the server.
+ *
+ * Note: with message delivery transports that have only one endpoint per
+ * logical destination, the above is the only information that needs to be
+ * maintained in a connection cache.
+ */
+typedef void (*SCACHE_SAVE_ENDP_FN) (SCACHE *, int, const char *, const char *, int);
+typedef int (*SCACHE_FIND_ENDP_FN) (SCACHE *, const char *, VSTRING *);
+
+ /*
+ * The following information is stored in order to make a binding from
+ * logical destination to physical destination. One logical destination can
+ * have multiple physical destinations (and one physical destination can
+ * have multiple sessions).
+ *
+ * - TTL for this binding.
+ *
+ * - Transport name and logical destination.
+ *
+ * In the case of SMTP: the next-hop (NOT: fall-back) destination domain and
+ * destination network port. It is not useful to create a link for an
+ * address literal (but it is not harmful either: it just wastes a few
+ * bits). This information specifies the destination domain in [] if no MX
+ * lookup is done.
+ *
+ * - Application-specific properties.
+ *
+ * In case the of SMTP, the properties specify a) whether a physical endpoint
+ * is best mx host with respect to a logical or fall-back destination (this
+ * information is needed by the loop detection code in smtp_proto.c).
+ *
+ * - Transport name and physical endpoint (see above).
+ *
+ * Note 1: there is no need to store the binding's MX preference or equivalent
+ * with respect to the logical destination; a client should store only the
+ * first successful session for a given delivery request (otherwise the
+ * client would keep talking to a less preferred server after the cached
+ * connection for a more preferred server expires). After a failed delivery,
+ * the client should not attempt to cache follow-up sessions with less
+ * preferred endpoints under the same logical destination.
+ *
+ * Note 2: logical to physical bindings exist independently from cached
+ * sessions. The two types of information have independent TTLs; creation
+ * and destruction proceed independently. Thus, a logical to physical
+ * binding can refer to an endpoint for which all cached connections are
+ * occupied or expired.
+ */
+typedef void (*SCACHE_SAVE_DEST_FN) (SCACHE *, int, const char *, const char *, const char *);
+typedef int (*SCACHE_FIND_DEST_FN) (SCACHE *, const char *, VSTRING *, VSTRING *);
+
+ /*
+ * Session cache statistics. These are the actual numbers at a specific
+ * point in time.
+ */
+struct SCACHE_SIZE {
+ int dest_count; /* Nr of destination names */
+ int endp_count; /* Nr of endpoint addresses */
+ int sess_count; /* Nr of cached sessions */
+};
+
+ /*
+ * Generic session cache object. Actual session cache objects are derived
+ * types with some additional, cache dependent, private information.
+ */
+struct SCACHE {
+ SCACHE_SAVE_ENDP_FN save_endp;
+ SCACHE_FIND_ENDP_FN find_endp;
+ SCACHE_SAVE_DEST_FN save_dest;
+ SCACHE_FIND_DEST_FN find_dest;
+ void (*size) (struct SCACHE *, SCACHE_SIZE *);
+ void (*free) (struct SCACHE *);
+};
+
+extern SCACHE *scache_single_create(void);
+extern SCACHE *scache_clnt_create(const char *, int, int, int);
+extern SCACHE *scache_multi_create(void);
+
+#define scache_save_endp(scache, ttl, endp_label, endp_prop, fd) \
+ (scache)->save_endp((scache), (ttl), (endp_label), (endp_prop), (fd))
+#define scache_find_endp(scache, endp_label, endp_prop) \
+ (scache)->find_endp((scache), (endp_label), (endp_prop))
+#define scache_save_dest(scache, ttl, dest_label, dest_prop, endp_label) \
+ (scache)->save_dest((scache), (ttl), (dest_label), (dest_prop), (endp_label))
+#define scache_find_dest(scache, dest_label, dest_prop, endp_prop) \
+ (scache)->find_dest((scache), (dest_label), (dest_prop), (endp_prop))
+#define scache_size(scache, stats) (scache)->size((scache), (stats))
+#define scache_free(scache) (scache)->free(scache)
+
+ /*
+ * Cache types.
+ */
+#define SCACHE_TYPE_SINGLE 1 /* single-instance cache */
+#define SCACHE_TYPE_CLIENT 2 /* session cache client */
+#define SCACHE_TYPE_MULTI 3 /* multi-instance cache */
+
+ /*
+ * Client-server protocol.
+ */
+#define SCACHE_REQ_FIND_ENDP "find_endp"
+#define SCACHE_REQ_SAVE_ENDP "save_endp"
+#define SCACHE_REQ_FIND_DEST "find_dest"
+#define SCACHE_REQ_SAVE_DEST "save_dest"
+
+ /*
+ * Session cache server status codes.
+ */
+#define SCACHE_STAT_OK 0 /* request completed successfully */
+#define SCACHE_STAT_BAD 1 /* malformed request */
+#define SCACHE_STAT_FAIL 2 /* request completed unsuccessfully */
+
+/* LICENSE
+/* .ad
+/* .fi
+/* The Secure Mailer license must be distributed with this software.
+/* AUTHOR(S)
+/* Wietse Venema
+/* IBM T.J. Watson Research
+/* P.O. Box 704
+/* Yorktown Heights, NY 10598, USA
+/*
+/* Wietse Venema
+/* Google, Inc.
+/* 111 8th Avenue
+/* New York, NY 10011, USA
+/*--*/
+
+#endif