summaryrefslogtreecommitdiffstats
path: root/src/util/auto_clnt.c
blob: 2703054e8039d70d0f99eda54e34b77aa3278cfb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
/*++
/* NAME
/*	auto_clnt 3
/* SUMMARY
/*	client endpoint maintenance
/* SYNOPSIS
/*	#include <auto_clnt.h>
/*
/*	AUTO_CLNT *auto_clnt_create(service, timeout, max_idle, max_ttl)
/*	const char *service;
/*	int	timeout;
/*	int	max_idle;
/*	int	max_ttl;
/*
/*	VSTREAM	*auto_clnt_access(auto_clnt)
/*	AUTO_CLNT *auto_clnt;
/*
/*	void	auto_clnt_recover(auto_clnt)
/*	AUTO_CLNT *auto_clnt;
/*
/*	const char *auto_clnt_name(auto_clnt)
/*	AUTO_CLNT *auto_clnt;
/*
/*	void	auto_clnt_free(auto_clnt)
/*	AUTO_CLNT *auto_clnt;
/* DESCRIPTION
/*	This module maintains IPC client endpoints that automatically
/*	disconnect after a being idle for a configurable amount of time,
/*	that disconnect after a configurable time to live,
/*	and that transparently handle most server-initiated disconnects.
/*
/*	This module tries each operation only a limited number of
/*	times and then reports an error.  This is unlike the
/*	clnt_stream(3) module which will retry forever, so that
/*	the application never experiences an error.
/*
/*	auto_clnt_create() instantiates a client endpoint.
/*
/*	auto_clnt_access() returns an open stream to the service specified
/*	to auto_clnt_create(). The stream instance may change between calls.
/*	The result is a null pointer in case of failure.
/*
/*	auto_clnt_recover() recovers from a server-initiated disconnect
/*	that happened in the middle of an I/O operation.
/*
/*	auto_clnt_name() returns the name of the specified client endpoint.
/*
/*	auto_clnt_free() destroys of the specified client endpoint.
/*
/*	Arguments:
/* .IP service
/*	The service argument specifies "transport:servername" where
/*	transport is currently limited to one of the following:
/* .RS
/* .IP inet
/*	servername has the form "inet:host:port".
/* .IP local
/*	servername has the form "local:private/servicename" or
/*	"local:public/servicename". This is the preferred way to
/*	specify Postfix daemons that are configured as "unix" in
/*	master.cf.
/* .IP unix
/*	servername has the form "unix:private/servicename" or
/*	"unix:public/servicename". This does not work on Solaris,
/*	where Postfix uses STREAMS instead of UNIX-domain sockets.
/* .RE
/* .IP timeout
/*	The time limit for sending, receiving, or for connecting
/*	to a server. Specify a value <=0 to disable the time limit.
/* .IP max_idle
/*	Idle time after which the client disconnects. Specify 0 to
/*	disable the limit.
/* .IP max_ttl
/*	Upper bound on the time that a connection is allowed to persist.
/*	Specify 0 to disable the limit.
/* .IP open_action
/*	Application call-back routine that opens a stream or returns a
/*	null pointer upon failure. In case of success, the call-back routine
/*	is expected to set the stream pathname to the server endpoint name.
/* .IP context
/*	Application context that is passed to the open_action routine.
/* DIAGNOSTICS
/*	Warnings: communication failure. Fatal error: out of memory.
/* 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
/*--*/

/* System library. */

#include <sys_defs.h>
#include <string.h>

/* Utility library. */

#include <msg.h>
#include <mymalloc.h>
#include <vstream.h>
#include <events.h>
#include <iostuff.h>
#include <connect.h>
#include <split_at.h>
#include <auto_clnt.h>

/* Application-specific. */

 /*
  * AUTO_CLNT is an opaque structure. None of the access methods can easily
  * be implemented as a macro, and access is not performance critical anyway.
  */
struct AUTO_CLNT {
    VSTREAM *vstream;			/* buffered I/O */
    char   *endpoint;			/* host:port or pathname */
    int     timeout;			/* I/O time limit */
    int     max_idle;			/* time before client disconnect */
    int     max_ttl;			/* time before client disconnect */
    int     (*connect) (const char *, int, int);	/* unix, local, inet */
};

static void auto_clnt_close(AUTO_CLNT *);

/* auto_clnt_event - server-initiated disconnect or client-side max_idle */

static void auto_clnt_event(int unused_event, void *context)
{
    AUTO_CLNT *auto_clnt = (AUTO_CLNT *) context;

    /*
     * Sanity check. This routine causes the stream to be closed, so it
     * cannot be called when the stream is already closed.
     */
    if (auto_clnt->vstream == 0)
	msg_panic("auto_clnt_event: stream is closed");

    auto_clnt_close(auto_clnt);
}

/* auto_clnt_ttl_event - client-side expiration */

static void auto_clnt_ttl_event(int event, void *context)
{

    /*
     * XXX This function is needed only because event_request_timer() cannot
     * distinguish between requests that specify the same call-back routine
     * and call-back context. The fix is obvious: specify a request ID along
     * with the call-back routine, but there is too much code that would have
     * to be changed.
     * 
     * XXX Should we be concerned that an overly aggressive optimizer will
     * eliminate this function and replace calls to auto_clnt_ttl_event() by
     * direct calls to auto_clnt_event()? It should not, because there exists
     * code that takes the address of both functions.
     */
    auto_clnt_event(event, context);
}

/* auto_clnt_open - connect to service */

static void auto_clnt_open(AUTO_CLNT *auto_clnt)
{
    const char *myname = "auto_clnt_open";
    int     fd;

    /*
     * Sanity check.
     */
    if (auto_clnt->vstream)
	msg_panic("auto_clnt_open: stream is open");

    /*
     * Schedule a read event so that we can clean up when the remote side
     * disconnects, and schedule a timer event so that we can cleanup an idle
     * connection. Note that both events are handled by the same routine.
     * 
     * Finally, schedule an event to force disconnection even when the
     * connection is not idle. This is to prevent one client from clinging on
     * to a server forever.
     */
    fd = auto_clnt->connect(auto_clnt->endpoint, BLOCKING, auto_clnt->timeout);
    if (fd < 0) {
	msg_warn("connect to %s: %m", auto_clnt->endpoint);
    } else {
	if (msg_verbose)
	    msg_info("%s: connected to %s", myname, auto_clnt->endpoint);
	auto_clnt->vstream = vstream_fdopen(fd, O_RDWR);
	vstream_control(auto_clnt->vstream,
			CA_VSTREAM_CTL_PATH(auto_clnt->endpoint),
			CA_VSTREAM_CTL_TIMEOUT(auto_clnt->timeout),
			CA_VSTREAM_CTL_END);
    }

    if (auto_clnt->vstream != 0) {
	close_on_exec(vstream_fileno(auto_clnt->vstream), CLOSE_ON_EXEC);
	event_enable_read(vstream_fileno(auto_clnt->vstream), auto_clnt_event,
			  (void *) auto_clnt);
	if (auto_clnt->max_idle > 0)
	    event_request_timer(auto_clnt_event, (void *) auto_clnt,
				auto_clnt->max_idle);
	if (auto_clnt->max_ttl > 0)
	    event_request_timer(auto_clnt_ttl_event, (void *) auto_clnt,
				auto_clnt->max_ttl);
    }
}

/* auto_clnt_close - disconnect from service */

static void auto_clnt_close(AUTO_CLNT *auto_clnt)
{
    const char *myname = "auto_clnt_close";

    /*
     * Sanity check.
     */
    if (auto_clnt->vstream == 0)
	msg_panic("%s: stream is closed", myname);

    /*
     * Be sure to disable read and timer events.
     */
    if (msg_verbose)
	msg_info("%s: disconnect %s stream",
		 myname, VSTREAM_PATH(auto_clnt->vstream));
    event_disable_readwrite(vstream_fileno(auto_clnt->vstream));
    event_cancel_timer(auto_clnt_event, (void *) auto_clnt);
    event_cancel_timer(auto_clnt_ttl_event, (void *) auto_clnt);
    (void) vstream_fclose(auto_clnt->vstream);
    auto_clnt->vstream = 0;
}

/* auto_clnt_recover - recover from server-initiated disconnect */

void    auto_clnt_recover(AUTO_CLNT *auto_clnt)
{

    /*
     * Clean up. Don't re-connect until the caller needs it.
     */
    if (auto_clnt->vstream)
	auto_clnt_close(auto_clnt);
}

/* auto_clnt_access - access a client stream */

VSTREAM *auto_clnt_access(AUTO_CLNT *auto_clnt)
{

    /*
     * Open a stream or restart the idle timer.
     * 
     * Important! Do not restart the TTL timer!
     */
    if (auto_clnt->vstream == 0) {
	auto_clnt_open(auto_clnt);
    } else {
	if (auto_clnt->max_idle > 0)
	    event_request_timer(auto_clnt_event, (void *) auto_clnt,
				auto_clnt->max_idle);
    }
    return (auto_clnt->vstream);
}

/* auto_clnt_create - create client stream object */

AUTO_CLNT *auto_clnt_create(const char *service, int timeout,
			            int max_idle, int max_ttl)
{
    const char *myname = "auto_clnt_create";
    char   *transport = mystrdup(service);
    char   *endpoint;
    AUTO_CLNT *auto_clnt;

    /*
     * Don't open the stream until the caller needs it.
     */
    if ((endpoint = split_at(transport, ':')) == 0
	|| *endpoint == 0 || *transport == 0)
	msg_fatal("need service transport:endpoint instead of \"%s\"", service);
    if (msg_verbose)
	msg_info("%s: transport=%s endpoint=%s", myname, transport, endpoint);
    auto_clnt = (AUTO_CLNT *) mymalloc(sizeof(*auto_clnt));
    auto_clnt->vstream = 0;
    auto_clnt->endpoint = mystrdup(endpoint);
    auto_clnt->timeout = timeout;
    auto_clnt->max_idle = max_idle;
    auto_clnt->max_ttl = max_ttl;
    if (strcmp(transport, "inet") == 0) {
	auto_clnt->connect = inet_connect;
    } else if (strcmp(transport, "local") == 0) {
	auto_clnt->connect = LOCAL_CONNECT;
    } else if (strcmp(transport, "unix") == 0) {
	auto_clnt->connect = unix_connect;
    } else {
	msg_fatal("invalid transport name: %s in service: %s",
		  transport, service);
    }
    myfree(transport);
    return (auto_clnt);
}

/* auto_clnt_name - return client stream name */

const char *auto_clnt_name(AUTO_CLNT *auto_clnt)
{
    return (auto_clnt->endpoint);
}

/* auto_clnt_free - destroy client stream instance */

void    auto_clnt_free(AUTO_CLNT *auto_clnt)
{
    if (auto_clnt->vstream)
	auto_clnt_close(auto_clnt);
    myfree(auto_clnt->endpoint);
    myfree((void *) auto_clnt);
}