-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
530 lines (389 loc) · 14.5 KB
/
README
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
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
DB_HTTP Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. SSL(int)
1.3.2. cap_raw_query(int)
1.3.3. cap_replace(int)
1.3.4. cap_insert_update(int)
1.3.5. cap_last_inserted_id(int)
1.3.6. field_delimiter (str)
1.3.7. row_delimiter (str)
1.3.8. quote_delimiter (str)
1.3.9. value_delimiter (str)
1.3.10. timeout (int)
1.3.11. disable_expect (int)
1.4. Exported Functions
1.5. Server specifications
1.5.1. Queries
1.5.2. Variables
1.5.3. Query Types
1.5.4. NULL values in queries
1.5.5. Server Replies
1.5.6. Reply Quoting
1.5.7. Last inserted id
1.5.8. Authentication and SSL
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors
List of Tables
2.1. Top contributors by DevScore^(1), authored commits^(2) and
lines added/removed^(3)
2.2. Most recently active contributors^(1) to this module
List of Examples
1.1. Setting db_url for a module
1.2. Set SSL parameter
1.3. Set cap_raw_query parameter
1.4. Set cap_replace parameter
1.5. Set cap_insert_update parameter
1.6. Set cap_last_inserted_id parameter
1.7. Set field_delimiter parameter
1.8. Set row_delimiter parameter
1.9. Set quote_delimiter parameter
1.10. Set value_delimiter parameter
1.11. Set timeout parameter
1.12. Set disable_expect parameter
1.13. Example query.
1.14. Example query with variables.
1.15. More query examples.
1.16. NULL query example.
1.17. Example Reply.
1.18. Quoting Example.
Chapter 1. Admin Guide
1.1. Overview
This module provides access to a database that is implemented
as a HTTP server. It may be used in special cases where
traversing firewalls is a problem, or where data encryption is
required.
In order to use this module you must have a server that can
communicate via HTTP or HTTPS with this module that follows
exactly the format decribed in the specifications section.
The module can provide SSL, authentication, and all the
functionalities of an opensips db as long as the server
supports them ( except result_fetch).
There is a slight difference between the url of db_http and the
urls of the other db modules. The url doesn't have to contain
the database name. Instead, everything that is after the
address is considered to be a path to the db resource, it may
be missing.
Even if using HTTPS the url must begin with "http://" , and the
SSL parameter for the module must be set to 1.
Example 1.1. Setting db_url for a module
...
modparam("presence", "db_url","http://user:pass@localhost:13100")
or
modparam("presence", "db_url","http://user:pass@www.some.com/some/some")
...
1.2. Dependencies
1.2.1. OpenSIPS Modules
This module does not depend on other modules.
1.2.2. External Libraries or Applications
* libcurl.
1.3. Exported Parameters
1.3.1. SSL(int)
Whether or not to use SSL.
If value is 1 the module will use https otherwise it will use
http.
Default value is “ 0 ”.
Example 1.2. Set SSL parameter
...
modparam("db_http", "SSL",1)
...
1.3.2. cap_raw_query(int)
Whether or not the server supports raw queries.
Default value is “0”.
Example 1.3. Set cap_raw_query parameter
...
modparam("db_http", "cap_raw_query", 1)
...
1.3.3. cap_replace(int)
Whether or not the server supports replace capabilities.
Default value is “0”.
Example 1.4. Set cap_replace parameter
...
modparam("db_http", "cap_replace", 1)
...
1.3.4. cap_insert_update(int)
Whether or not the server supports insert_update capabilities.
Default value is “0”.
Example 1.5. Set cap_insert_update parameter
...
modparam("db_http", "cap_insert_update", 1)
...
1.3.5. cap_last_inserted_id(int)
Whether or not the server supports last_inserted_id
capabilities.
Default value is “0”.
Example 1.6. Set cap_last_inserted_id parameter
...
modparam("db_http", "cap_last_inserted_id", 1)
...
1.3.6. field_delimiter (str)
Character to be used to delimit fields in the reply.Only one
char may be set.
Default value is “;”
Example 1.7. Set field_delimiter parameter
...
modparam("db_http", "field_delimiter",";")
...
1.3.7. row_delimiter (str)
Character to be used to delimit rows in the reply.Only one char
may be set.
Default value is “\n”
Example 1.8. Set row_delimiter parameter
...
modparam("db_http", "row_delimiter","\n")
...
1.3.8. quote_delimiter (str)
Character to be used to quote fields that require quoting in
the reply.Only one char may be set.
Default value is “|”
Example 1.9. Set quote_delimiter parameter
...
modparam("db_http", "quote_delimiter","|")
...
1.3.9. value_delimiter (str)
The delimiter used to separate multiple fields of a single
variable (see Section 1.5.2, “Variables”). Only one char may be
set.
Default value is “,”
Example 1.10. Set value_delimiter parameter
...
modparam("db_http", "value_delimiter",";")
...
1.3.10. timeout (int)
The maximum number of milliseconds that the HTTP ops are
allowed to last
Default value is “30000 ( 30 seconds )”
Example 1.11. Set timeout parameter
...
modparam("db_http", "timeout",5000)
...
1.3.11. disable_expect (int)
Disables automatic 'Expect: 100-continue' behavior in libcurl
for requests over 1024 bytes in size. This can help reduce
latency by saving a network round-trip for large records. For
more information on this behavior please seee rfc2616 section
8.2.3.
Default value is “0 (off)”
Example 1.12. Set disable_expect parameter
...
modparam("db_http", "disable_expect",1)
...
1.4. Exported Functions
This module does not export any functions.
1.5. Server specifications
1.5.1. Queries
The server must accept queries as HTTP queries.
The queries are of 2 types : GET and POST.Both set variables
that must be interpreted by the server. All values are
URL-encoded.
There are several types of queries and the server can tell them
apart by the query_type variable. Each type of query uses
specific variables simillar to those in the opensips db_api.
Example 1.13. Example query.
...
GET /presentity/?c=username,domain,event,expires HTTP/1.1
...
1.5.2. Variables
A description of all the variables. Each variable can have
either a single value or a comma-separated list of values. Each
variable has a special meaning and can be used only with
certain queries.
The table on which operations will take place will be encoded
in the url as the end of the url ( www.some.com/users will
point to the users table).
* k=
Describes the keys (columns) that will be used for
comparison.Can have multiple values.
* op=
Describes the operators that will be used for
comparison.Can have multiple values.
* v=
Describes the values that columns will be compaired
against. Can have multiple values.
* c=
Describes the columns that will be selected from the
result.Can have multiple values.
* o=
The column that the result will be ordered by. Has a single
value.
* uk=
The keys(columns) that will be updated. Can have multiple
values.
* uv=
The new values that will be put in the columns. Can have
multiple values.
* q=
Describes a raw query. Will only be used if the server
supports raw queries. Has a single value.
* query_type=
Describes the type of the current query. Can have a single
value as described in the Query Types section.Has a single
value. Will be present in all queries except the "SELECT"
(normal query).
Example 1.14. Example query with variables.
...
GET /presentity/?c=username,domain,event,expires HTTP/1.1
GET /version/?k=table_name&v=xcap&c=table_version HTTP/1.1
...
...
POST /active_watchers HTTP/1.1
k=id&v=100&query_type=insert
...
1.5.3. Query Types
The types of the queries are described by the query_type
variable. The value of the variable will be set to the exact
name of the query.
Queries for "SELECT" use GET and the rest use POST (insert,
update, delete, replace, insert_update).
* normal query
Uses the k, op, v, c and o variables. This will not set the
query_type variable and will use GET.
* delete
Uses the k, op and v variables.
* insert
Uses the k and v variables.
* update
Uses the k,op,v,uk and uv variables.
* replace
Uses the k and v variables. This is an optional type of
query. If the module is not configured to use it it will
not.
* insert_update
Uses the k and v variables. This is an optional type of
query. If the module is not configured to use it it will
not.
* custom
Uses the q variable. This is an optional type of query. If
the module is not configured to use it it will not.
Example 1.15. More query examples.
...
POST /active_watchers HTTP/1.1
k=id&op=%3D&v=100&query_type=delete
...
...
POST /active_watchers HTTP/1.1
k=id&op=%3D&v=100&uk=id&uv=101&query_type=update
...
1.5.4. NULL values in queries
NULL values in queries are represented as a string of length 1
containing a single character with value '\0'.
Example 1.16. NULL query example.
...
POST /active_watchers HTTP/1.1
k=id&op=%3D&v=%00&query_type=delete
...
1.5.5. Server Replies
If the query is ok (even if the answer is empty) the server
must reply with a 200 OK HTTP reply with a body containing the
types and values of the columns.
The server must reply with a delimiter separated list of values
and columns.
Each element in the list must be seperated from the one before
it by a field delimiter that must be the same as the one set as
a parameter from the script for the module. The last element of
each line must not be followed by a field delimiter, but by a
row delimiter.
The first line of the reply must contain a list of the types of
values of each column. The types can be any from the list:
integer, string, str, blob, date.
Each following line contains the values of each row from the
result.
If the query produced an error the server must reply with a
HTTP 500 reply, or with a corresponding error code (404, 401).
Example 1.17. Example Reply.
...
int;string;blob
6;something=something;1000
100;mine;10002030
...
1.5.6. Reply Quoting
Because the values may contain delimiters inside, the server
must perform quoting when necessary (there is no problem if it
does it even when it is not necessary).
A quote delimiter must be defined and must be the same as the
one set from the script ( by default it is "|" ).
If a value contains a field , row or a quote delimiter it must
be placed under quotes. A quote delimiter inside a value must
be preceeded by another quote delimiter.
Example 1.18. Quoting Example.
...
int;string;blob
6;|ana;maria|;1000
100;mine;10002030
3;mine;|some||more;|
...
1.5.7. Last inserted id
This is an optional feature and may be enabled if one wants to
use it.
In order to use this feature the server must place the id of
the last insert in the 200 reply for each insert query.
1.5.8. Authentication and SSL
If the server supports authentication and SSL, the module can
be enabled to use SSL. Authentication will always be used if
needed.
The module will try to use the most secure type of
authentication that is provided by the server from: Basic,
Digest,GSSNEGOTIATE and NTLM.
Chapter 2. Contributors
2.1. By Commit Statistics
Table 2.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Andrei Dragus 21 2 2289 5
2. Razvan Crainea (@razvancrainea) 12 10 69 18
3. Liviu Chircu (@liviuchircu) 9 7 24 46
4. Bogdan-Andrei Iancu (@bogdan-iancu) 8 6 47 51
5. Vlad Paiu (@vladpaiu) 6 4 65 7
6. Vlad Patrascu (@rvlad-patrascu) 5 3 58 5
7. Ryan Bullock (@rrb3942) 5 3 42 1
8. Dusan Klinec (@ph4r05) 3 1 50 26
9. Anca Vamanu 3 1 1 1
10. Ezequiel Lovelle (@lovelle) 3 1 1 1
All remaining contributors: Peter Lemenkov (@lemenkov),
Stephane Alnet.
(1) DevScore = author_commits + author_lines_added /
(project_lines_added / project_commits) + author_lines_deleted
/ (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding
merge commits. Regarding imported patches/code, we do our best
to count the work on behalf of the proper owner, as per the
"fix_authors" and "mod_renames" arrays in
opensips/doc/build-contrib.sh. If you identify any
patches/commits which do not get properly attributed to you,
please submit a pull request which extends "fix_authors" and/or
"mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated
files
2.2. By Commit Activity
Table 2.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Vlad Patrascu (@rvlad-patrascu) May 2017 - Feb 2021
2. Razvan Crainea (@razvancrainea) Oct 2011 - Sep 2019
3. Bogdan-Andrei Iancu (@bogdan-iancu) Dec 2009 - Apr 2019
4. Ryan Bullock (@rrb3942) Jan 2019 - Feb 2019
5. Peter Lemenkov (@lemenkov) Jun 2018 - Jun 2018
6. Liviu Chircu (@liviuchircu) Mar 2014 - Jun 2018
7. Dusan Klinec (@ph4r05) Dec 2015 - Dec 2015
8. Ezequiel Lovelle (@lovelle) Oct 2014 - Oct 2014
9. Stephane Alnet Nov 2013 - Nov 2013
10. Vlad Paiu (@vladpaiu) Apr 2013 - Aug 2013
All remaining contributors: Anca Vamanu, Andrei Dragus.
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Ryan Bullock (@rrb3942), Peter Lemenkov
(@lemenkov), Liviu Chircu (@liviuchircu), Razvan Crainea
(@razvancrainea), Stephane Alnet, Vlad Paiu (@vladpaiu),
Bogdan-Andrei Iancu (@bogdan-iancu), Andrei Dragus.
Documentation Copyrights:
Copyright © 2009 Voice Sistem SRL