tm: Number of fixes in code and documentation for serial forking.
[sip-router] / modules / tm / t_serial.c
1 /*
2  * Serial forking functions
3  *
4  * Copyright (C) 2008 Juha Heinanen
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are met:
8  *
9  *  1. Redistributions of source code must retain the above copyright notice,
10  *     this list of conditions and the following disclaimer.
11  *  2. Redistributions in binary form must reproduce the above copyright
12  *     notice, this list of conditions and the following disclaimer in the
13  *     documentation and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE FREEBSD PROJECT ``AS IS'' AND ANY EXPRESS OR
16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
17  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
18  * EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
19  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
20  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
23  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
24  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  *
26  * History:
27  * -------
28  *  2008-10-22: Moved functions from lcr module to tm module (jh)
29  */
30
31 #include "../../qvalue.h"
32 #include "../../mem/mem.h"
33 #include "../../socket_info.h"
34 #include "../../usr_avp.h"
35 #include "../../dset.h"
36 #include "../../parser/msg_parser.h"
37 #include "../../ut.h"
38 #include "config.h"
39 #include "t_funcs.h"
40 #include "t_lookup.h"
41
42 /* usr_avp flag for sequential forking */
43 #define Q_FLAG      (1<<2)
44
45 /* Struture where information regarding contacts is stored */
46 struct contact {
47     str uri;
48     qvalue_t q;
49     str dst_uri;
50     str path;
51     unsigned int flags;
52     struct socket_info* sock;
53     unsigned short q_flag;
54     struct contact *next;
55 };
56
57 /* 
58  * Frees contact list used by load_contacts function
59  */
60 static inline void free_contact_list(struct contact *curr) {
61     struct contact *prev;
62     while (curr) {
63                 prev = curr;
64                 curr = curr->next;
65                 pkg_free(prev);
66     }
67 }
68
69 /* Encode branch info from contact struct to str */
70 static inline int encode_branch_info(str *info, struct contact *con)
71 {
72     char *at, *s;
73     int len;
74
75     info->len = con->uri.len + con->dst_uri.len +
76                 con->path.len + MAX_SOCKET_STR + INT2STR_MAX_LEN + 5;
77     info->s = pkg_malloc(info->len);
78     if (!info->s) {
79                 LM_ERR("no memory left for branch info\n");
80                 return 0;
81     }
82     at = info->s;
83     append_str(at, con->uri.s, con->uri.len);
84     append_chr(at, '\n');
85     append_str(at, con->dst_uri.s, con->dst_uri.len);
86     append_chr(at, '\n');
87     append_str(at, con->path.s, con->path.len);
88     append_chr(at, '\n');
89     if (con->sock) {
90                 len = MAX_SOCKET_STR;
91                 if (socket2str(at, &len, con->sock) < 0) {
92                         LM_ERR("failed to convert socket to str\n");
93                         return 0;
94                 }
95     } else {
96                 len = 0;
97     }
98     at = at + len;
99     append_chr(at, '\n');
100     s = int2str(con->flags, &len);
101     append_str(at, s, len);
102     append_chr(at, '\n');
103     info->len = at - info->s + 1;
104
105     return 1;
106 }
107
108
109 /* Encode branch info from str */
110 static inline int decode_branch_info(char *info, str *uri, str *dst, str *path,
111                                                                          struct socket_info **sock,
112                                                                          unsigned int *flags)
113 {
114     str s, host;
115     int port, proto;
116     char *pos, *at, *tmp;
117
118         if (info == NULL) {
119                 ERR("decode_branch_info: Invalid input string.\n");
120                 return 0;
121         }
122         
123         /* Reset or return arguments to sane defaults */
124         uri->s = 0; uri->len = 0;
125         dst->s = 0; dst->len = 0;
126         path->s = 0; path->len = 0;
127         *sock = NULL;
128         *flags = 0;
129         
130         /* Make sure that we have at least a non-empty URI string, it is fine if
131          * everything else is missing, but we need at least the URI. */
132         uri->s = info; 
133         if ((pos = strchr(info, '\n')) == NULL) { 
134                 uri->len = strlen(info); 
135                         /* We don't even have the URI string, this is bad, report an
136                          * error. */
137                 if (uri->len == 0) goto uri_missing;
138                 return 1;
139     }
140         uri->len = pos - info;
141         if (uri->len == 0) goto uri_missing;
142
143         /* If we get here we have at least the branch URI, now try to parse as
144          * much as you can. All output variable have been initialized above, so it
145          * is OK if any of the fields are missing from now on. */
146     dst->s = at = pos + 1;
147     if ((pos = strchr(at, '\n')) == NULL) {
148                 dst->len = strlen(dst->s);
149                 return 1;
150     }
151         dst->len = pos - at;
152
153     path->s = at = pos + 1;
154     if ((pos = strchr(at, '\n')) == NULL) {
155                 path->len = strlen(path->s);
156                 return 1;
157     }
158     path->len = pos - at;
159
160     s.s = at = pos + 1;
161     if ((pos = strchr(at, '\n')) == NULL) {
162                 /* No LF found, that means we take the string till the final zero
163                  * termination character and pass it directly to parse_phostport
164                  * without making a zero-terminated copy. */
165                 tmp = s.s;
166                 s.len = strlen(s.s);
167         } else {
168                 /* Our string is terminated by LF, so we need to make a
169                  * zero-terminated copy of the string before we pass it to
170                  * parse_phostport. */
171                 s.len = pos - at;
172                 if ((tmp = as_asciiz(&s)) == NULL) {
173                         ERR("No memory left\n");
174                         return 0;
175                 }
176         }       
177         if (s.len) {
178                 if (parse_phostport(tmp, &host.s, &host.len,
179                                                         &port, &proto) != 0) {
180                         LM_ERR("parsing of socket info <%s> failed\n", tmp);
181                         if (pos) pkg_free(tmp);
182                         return 0;
183                 }
184
185                 *sock = grep_sock_info(&host, (unsigned short)port,
186                                                            (unsigned short)proto);
187                 if (*sock == 0) {
188                         LM_ERR("invalid socket <%s>\n", tmp);
189                         if (pos) pkg_free(tmp);
190                         return 0;
191                 }
192         }
193         
194         if (pos) pkg_free(tmp);
195         else return 1;
196         
197     s.s = at = pos + 1;
198     if ((pos = strchr(at, '\n')) == NULL) s.len = strlen(s.s);
199     else s.len = pos - s.s;
200
201     if (s.len) {
202                 if (str2int(&s, flags) != 0) {
203                         LM_ERR("failed to decode flags <%.*s>\n", STR_FMT(&s));
204                         return 0;
205                 }
206     }
207     return 1;
208
209 uri_missing:
210         ERR("decode_branch_info: Cannot decode branch URI.\n");
211         return 0;
212 }
213
214
215 /* 
216  * Loads contacts in destination set into contacts_avp in reverse
217  * priority order and associated each contact with Q_FLAG telling if
218  * contact is the last one in its priority class.  Finally, removes
219  * all branches from destination set.
220  */
221 int t_load_contacts(struct sip_msg* msg, char* key, char* value)
222 {
223     str uri, tmp, dst_uri, path, branch_info, *ruri;
224     qvalue_t first_q, q;
225     struct contact *contacts, *next, *prev, *curr;
226     int_str val;
227     int first_idx, idx;
228     struct socket_info* sock;
229     unsigned int flags;
230     struct cell *t;
231
232     /* Check if contacts_avp has been defined */
233     if (contacts_avp.n == 0) {
234                 LM_ERR("feature has been disabled - "
235                            "to enable define contacts_avp module parameter");
236                 return -1;
237     }
238
239     /* Check if anything needs to be done */
240     if (nr_branches == 0) {
241                 LM_DBG("nothing to do - no branches!\n");
242                 return 1;
243     }
244
245     t = get_t();
246     ruri = (str *)0;
247
248     if (!t || (t == T_UNDEFINED)) {
249
250                 /* No transaction yet - take first q from Request-URI */
251                 ruri = GET_RURI(msg);
252                 if (!ruri) {
253                         LM_ERR("no Request-URI found\n");
254                         return -1;
255                 }
256                 first_q = get_ruri_q();
257                 first_idx = 0;
258
259     } else {
260
261                 /* Transaction exists - take first q from first branch */
262         
263                 uri.s = get_branch(0, &uri.len, &first_q, &dst_uri, &path, &flags,
264                                                    &sock);
265                 first_idx = 1;
266
267     }
268
269     /* Check if all q values are equal */
270     for(idx = first_idx; (tmp.s = get_branch(idx, &tmp.len, &q, 0, 0, 0, 0))
271                         != 0; idx++) {
272                 if (q != first_q) {
273                         goto rest;
274                 }
275     }
276
277     LM_DBG("nothing to do - all contacts have same q!\n");
278     return 1;
279
280 rest:
281
282     /* Allocate memory for first contact */
283     contacts = (struct contact *)pkg_malloc(sizeof(struct contact));
284     if (!contacts) {
285                 LM_ERR("no memory for contact info\n");
286                 return -1;
287     }
288
289     if (!t || (t == T_UNDEFINED)) {
290
291                 /* Insert Request-URI branch to first contact */
292                 contacts->uri.s = ruri->s;
293                 contacts->uri.len = ruri->len;
294                 contacts->dst_uri = msg->dst_uri;
295                 contacts->sock = msg->force_send_socket;
296                 getbflagsval(0, &contacts->flags);
297                 contacts->path = msg->path_vec;
298
299     } else {
300         
301                 /* Insert first branch to first contact */
302                 contacts->uri = uri;
303                 contacts->q = first_q;
304                 contacts->dst_uri = dst_uri;
305                 contacts->sock = sock;
306                 contacts->flags = flags;
307                 contacts->path = path;
308     }
309
310     contacts->q = first_q;
311     contacts->next = (struct contact *)0;
312
313     /* Insert (remaining) branches to contact list in increasing q order */
314
315     for(idx = first_idx;
316                 (uri.s = get_branch(idx,&uri.len,&q,&dst_uri,&path,&flags,&sock))
317                         != 0;
318                 idx++ ) {
319                 next = (struct contact *)pkg_malloc(sizeof(struct contact));
320                 if (!next) {
321                         LM_ERR("no memory for contact info\n");
322                         free_contact_list(contacts);
323                         return -1;
324                 }
325                 next->uri = uri;
326                 next->q = q;
327                 next->dst_uri = dst_uri;
328                 next->path = path;
329                 next->flags = flags;
330                 next->sock = sock;
331                 next->next = (struct contact *)0;
332                 prev = (struct contact *)0;
333                 curr = contacts;
334                 while (curr && (curr->q < q)) {
335                         prev = curr;
336                         curr = curr->next;
337                 }
338                 if (!curr) {
339                         next->next = (struct contact *)0;
340                         prev->next = next;
341                 } else {
342                         next->next = curr;
343                         if (prev) {
344                                 prev->next = next;
345                         } else {
346                                 contacts = next;
347                         }
348                 }    
349     }
350
351     /* Assign values for q_flags */
352     curr = contacts;
353     curr->q_flag = 0;
354     while (curr->next) {
355                 if (curr->q < curr->next->q) {
356                         curr->next->q_flag = Q_FLAG;
357                 } else {
358                         curr->next->q_flag = 0;
359                 }
360                 curr = curr->next;
361     }
362
363     /* Add contacts to contacts_avp */
364     curr = contacts;
365     while (curr) {
366                 if (encode_branch_info(&branch_info, curr) == 0) {
367                         LM_ERR("encoding of branch info failed\n");
368                         free_contact_list(contacts);
369                         if (branch_info.s) pkg_free(branch_info.s);
370                         return -1;
371                 }
372                 val.s = branch_info;
373                 add_avp(contacts_avp_type|AVP_VAL_STR|(curr->q_flag),
374                                 contacts_avp, val);
375                 pkg_free(branch_info.s);
376                 LM_DBG("loaded contact <%.*s> with q_flag <%d>\n",
377                            STR_FMT(&val.s), curr->q_flag);
378                 curr = curr->next;
379     }
380
381     /* Clear all branches */
382     clear_branches();
383
384     /* Free contact list */
385     free_contact_list(contacts);
386
387     return 1;
388 }
389
390
391 /*
392  * Adds to request a destination set that includes all highest priority
393  * class contacts in contacts_avp.   If called from a route block,
394  * rewrites the request uri with first contact and adds the remaining
395  * contacts as branches.  If called from failure route block, adds all
396  * contacts as branches.  Removes added contacts from contacts_avp.
397  */
398 int t_next_contacts(struct sip_msg* msg, char* key, char* value)
399 {
400     struct usr_avp *avp, *prev;
401     int_str val;
402     str uri, dst, path;
403     struct socket_info *sock;
404     unsigned int flags;
405     struct cell *t;
406         struct search_state st;
407         ticks_t orig;
408         unsigned int avp_timeout;
409
410     /* Check if contacts_avp has been defined */
411     if (contacts_avp.n == 0) {
412                 LM_ERR("feature has been disabled - "
413                            "to enable define contacts_avp module parameter");
414                 return -1;
415     }
416
417     t = get_t();
418
419     if (!t || (t == T_UNDEFINED)) {
420
421                 /* no transaction yet => load Request-URI and branches */
422
423                 if (route_type == FAILURE_ROUTE) {
424                         LM_CRIT("BUG - undefined transaction in failure route\n");
425                         return -1;
426                 }
427
428                 /* Find first contacts_avp value */
429                 avp = search_first_avp(contacts_avp_type, contacts_avp, &val, &st);
430                 if (!avp) {
431                         LM_DBG("no AVPs - we are done!\n");
432                         return 1;
433                 }
434
435                 LM_DBG("next contact is <%.*s>\n", STR_FMT(&val.s));
436
437                 if (decode_branch_info(val.s.s, &uri, &dst, &path, &sock, &flags)
438                         == 0) {
439                         LM_ERR("decoding of branch info <%.*s> failed\n", STR_FMT(&val.s));
440                         destroy_avp(avp);
441                         return -1;
442                 }
443
444                 /* Rewrite Request-URI */
445                 rewrite_uri(msg, &uri);
446                 if (dst.s && dst.len) set_dst_uri(msg, &dst);
447                 else reset_dst_uri(msg);
448                 if (path.s && path.len) set_path_vector(msg, &path);
449                 else reset_path_vector(msg);
450                 msg->force_send_socket = sock;
451                 setbflagsval(0, flags);
452
453                 if (avp->flags & Q_FLAG) {
454                         destroy_avp(avp);
455                         /* Set fr_inv_timer */
456                         if (t_set_fr(msg, cfg_get(tm, tm_cfg, fr_inv_timeout_next), 0) 
457                                 == -1) {
458                                 ERR("Cannot set fr_inv_timer value.\n");
459                                 return -1;
460                         }
461                         return 1;
462                 }
463                 
464                 /* Append branches until out of branches or Q_FLAG is set */
465                 prev = avp;
466                 while ((avp = search_next_avp(&st, &val))) {
467                         destroy_avp(prev);
468                         LM_DBG("next contact is <%.*s>\n", STR_FMT(&val.s));
469
470                         if (decode_branch_info(val.s.s, &uri, &dst, &path, &sock, &flags)
471                                 == 0) {
472                                 LM_ERR("decoding of branch info <%.*s> failed\n", STR_FMT(&val.s));
473                                 destroy_avp(avp);
474                                 return -1;
475                         }
476
477                         if (append_branch(msg, &uri, &dst, &path, 0, flags, sock) != 1) {
478                                 LM_ERR("appending branch failed\n");
479                                 destroy_avp(avp);
480                                 return -1;
481                         }
482
483                         if (avp->flags & Q_FLAG) {
484                                 destroy_avp(avp);
485                                 /* Set fr_inv_timer */
486                                 if (t_set_fr(msg, cfg_get(tm, tm_cfg, fr_inv_timeout_next), 0) == -1) {
487                                         ERR("Cannot set fr_inv_timer value.\n");
488                                         return -1;
489                                 }
490                                 return 1;
491                         }
492                         prev = avp;
493                 }
494                 destroy_avp(prev);
495     } else {
496                         /* Transaction exists => only load branches */
497
498                 /* Find first contacts_avp value */
499                 avp = search_first_avp(contacts_avp_type, contacts_avp, &val, &st);
500                 if (!avp) return -1;
501
502                 /* Append branches until out of branches or Q_FLAG is set */
503                 do {
504                         LM_DBG("next contact is <%.*s>\n", STR_FMT(&val.s));
505
506                         if (decode_branch_info(val.s.s, &uri, &dst, &path, &sock, &flags)
507                                 == 0) {
508                                 LM_ERR("decoding of branch info <%.*s> failed\n", STR_FMT(&val.s));
509                                 destroy_avp(avp);
510                                 return -1;
511                         }
512         
513                         if (append_branch(msg, &uri, &dst, &path, 0, flags, sock) != 1) {
514                                 LM_ERR("appending branch failed\n");
515                                 destroy_avp(avp);
516                                 return -1;
517                         }
518
519                         if (avp->flags & Q_FLAG) {
520                                 destroy_avp(avp);
521                                 return 1;
522                         }
523
524                         prev = avp;
525                         avp = search_next_avp(&st, &val);
526                         destroy_avp(prev);
527                 } while (avp);
528
529                 /* If we got there then we have no more branches for subsequent serial
530                  * forking and the current set is the last one. For the last set we do
531                  * not use the shorter timer fr_inv_timer_next anymore, instead we use
532                  * the usual fr_inv_timer.
533                  *
534                  * There are three places in sip-router which can contain the actual
535                  * value of the fr_inv_timer. The first place is the variable
536                  * use_fr_inv_timeout defined in timer.c That variable is set when the
537                  * script writer calls t_set_fr in the script. Its value can only be
538                  * used from within the process in which t_set_fr was called. It is
539                  * not guaranteed that when we get here we are still in the same
540                  * process and therefore we might not be able to restore the correct
541                  * value if the script writer used t_set_fr before calling
542                  * t_next_contacts. If that happens then the code below detects this
543                  * and looks into the AVP or cfg framework for other value. In other
544                  * words, t_next_contact does not guarantee that fr_inv_timer values
545                  * configured on per-transaction basis with t_set_fr will be correctly
546                  * restored.
547                  *
548                  * The second place is the fr_inv_timer_avp configured in modules
549                  * parameters. If that AVP exists and then its value will be correctly
550                  * restored by t_next_contacts. The AVP is an alternative way of
551                  * configuring fr_inv_timer on per-transaction basis, it can be used
552                  * interchangeably with t_set_fr. Function t_next_contacts always
553                  * correctly restores the timer value configured in the AVP.
554                  *
555                  * Finally, if we can get the value neither from user_fr_inv_timeout
556                  * nor from the AVP, we turn to the fr_inv_timeout variable in the cfg
557                  * framework. This variable contains module's default and it always
558                  * exists and is available. */
559                 orig = (ticks_t)get_msgid_val(user_fr_inv_timeout, msg->id, int);
560                 if (orig == 0) {
561                         if (!fr_inv_avp2timer(&avp_timeout)) {
562                                 /* The value in the AVP is in seconds and needs to be
563                                  * converted to ticks */
564                                 orig = S_TO_TICKS((ticks_t)avp_timeout);
565                         } else {
566                                 orig = cfg_get(tm, tm_cfg, fr_inv_timeout);
567                         }
568                 }
569                 change_fr(t, orig, 0);
570     }
571
572     return 1;
573 }