compression Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. How it works
1.3. Usage cases
1.4. Dependencies
1.4.1. OpenSIPS Modules
1.5. External Libraries or Applications
1.6. Exported Parameters
1.6.1. mc_level (int)
1.7. Exported Functions
1.7.1. mc_compress([algo], flags, [whitelist])
1.7.2. mc_compact([whitelist])
1.7.3. mc_decompress()
1.8. Compression performance test for sip messages
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors
List of Tables
1.1. mc_compress performance test results
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. Set mc_level parameter
1.2. mc_compress usage
1.3. mc_compress usage
1.4. mc_compress usage
1.5. mc_decompress usage
Chapter 1. Admin Guide
1.1. Overview
This module implements message compression/decompression and
base64 encoding for sip messages using deflate and gzip
algorithm/headers. Another feature of this module is reducing
headers to compact for as specified in SIP RFC's, sdp body
codec unnecessary description removal (for codecs 0-97),
whitelist for headers not be removed (excepting necessary
headers).
1.2. How it works
The module is using zlib library to implement compression and
base64 encoding for converting the message to human readable
characters. It also uses callbacks to do the
compression/compaction of the message in order for this
operations to be done after all the other script functions have
been applied to the message.
1.3. Usage cases
As we know, udp fragmentation is a big problem these days, so
this module comes to try making the message smaller by any
means. The module can be used to compress the body or some
headers found in the message or it can decompress compressed
messages. There are more possibilities to do this: the body can
be compressed along with the specified headers or the headers
can be compressed isolated from the body in a specific header.
Also the module does message compaction: reduction of sip
header names to short form (for example "Via" becomes 'v' and
so on), sdp body codec attributes unnecesary description
("a=rtpmap:0 PCMU/8000" becomes "a=rtpmap:0"), unwanted headers
removal by specfing the ones you want to keep in a whitelist.
The module also does message decompresion and base64 decoding.
It can detect the algorithm used for compression from the
Content-Encoding header. At this moment only gzip and deflate
algorithms are supported.
1.4. Dependencies
1.4.1. OpenSIPS Modules
The following modules must be loaded before this module:
* None
1.5. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* zlib-dev - the development libraries of zlib.
1.6. Exported Parameters
1.6.1. mc_level (int)
This parameter ranges from 1 to 9 and it specifies the level of
compression you want to do. Default is 6. 9 is the best, but
the longest time consuming algorithm and 1 is the worst. If, by
mistake, you set a lower or a higher level, the default, 6,
will be used, but you will receive a warning.
Example 1.1. Set mc_level parameter
...
modparam("mc", "mc_level", "3")
...
1.7. Exported Functions
1.7.1. mc_compress([algo], flags, [whitelist])
This function will compress the current message as specified in
the parameters. Keep in mind that the compression is done just
before the message is sent, so that all your lumps can be
applied.
Meaning of the parameters is as follows:
* algo (int, optional) - The algorithm used for compression.
Currently implemented are deflate ('0') and gzip ('1').
* flags (string) - Specifies on what to apply the compression
and where to put the result of the compression.
The flags parameter can have the following values:
+ "b" - specifies that the body of the message shall be
compressed. Notice that if the message has no body,
the flag will have no effect.
+ "h" - specifies that all the headers, except the
mandatory ones (which will be specified in "whitelist"
parameter section) and the ones in the whitelist shall
be compressed.
+ "s" - the headers and the body shall be compressed
Separately, meaning that a new header named
"Comp-Hdrs" will be created, and this header will keep
the content of the compressed headers. Also,
"Headers-Encoding" header will be created in order to
keep the algorithm used to compress the headers. If
this flag is not specified, the headers and the body
(if 'b' and 'h' flags are specified) will be
compressed alltogether in the new body of the message.
+ "e" - specify that you want base64 Encoding. If you do
not specify this flag, by default the module will send
the raw compressed message in deflate/gzip format.
* whitelist (string, optional) - header names list, separated
by '|' which will specify which headers shall not be
compressed, along with the mandatory ones, which can never
be compressed. The mandatory headers are the following:
VIA, FROM, TO, CSEQ, ROUTE, RECORD_ROUTE, CALLID. Also,
CONTENT_TYPE is mandatory only if CONTENT-LENGTH > 0. Also,
in case you do not want to use body compression, the
Content-Length header will become a mandatory header, which
can not be compressed. In case you do want body
compression, the old Content-Length Header will be
compressed, and a new content length will be calculated.
When you will want to do decompression, the compressed
length will be removed, and the content length header will
be the same as the one before the compression.
This function can be used from REQUEST_ROUTE, LOCAL_ROUTE,
FAILURE_ROUTE.
Example 1.2. mc_compress usage
...
if (!mc_compress(0, "bhs", "Max-Forwards|Subject|P-Asserted-Identity"))
xlog("compression failed\n");
...
Example 1.3. mc_compress usage
...
$avp(algo) = 1;
$var(flags) = "bs";
$var(list) = "Max-Forwards | Contact";
mc_compres($avp(algo), $var(flags), $var(list);
xlog("compression registered\n");
...
1.7.2. mc_compact([whitelist])
This function will realise four different things: headers which
are not mandatory and are not in the whitelist will be removed,
headers of same type will be merged together, separated by ',',
header names which have a short form will be reduced to that
short form and SDP rtpmap attribute headers which contain a
value lower than 96 will be removed, because they are not
mandatory. Lumps are not affected by this function, because it
is applied after all messages changes are processed. done. The
mc_compact supported short forms are:
* "c" - Content-Type (RFC 3261)
* "f" - From (RFC 3261)
* "i" - Call-ID (RFC 3261)
* "k" - Supported (RFC 3261)
* "l" - Content-Length (RFC 3261)
* "m" - Contact (RFC 3261)
* "s" - Subject (RFC 3261)
* "t" - To (RFC 3261)
* "v" - Via (RFC 3261)
* "x" - Session-Expires (RFC 4028)
Meaning of the parameters is as follows:
* whitelist (string, optional) - Whitelist of headers not to
be removed, except from the mandatory ones. The whitelist
header names must pe separated by '|'.
This function can be used from REQUEST_ROUTE, LOCAL_ROUTE,
FAILURE_ROUTE.
Example 1.4. mc_compress usage
...
if (!mc_compact("Max-Forwards|P-Asserted-Identity"))
xlog("compaction failed\n");
...
1.7.3. mc_decompress()
This function does the reverse of mc_compress, meaning that it
does base64 decoding and gzip/deflate decompression. Keep in
mind that gzip decompression is a little bit more efficient
because it is being known the size of the compressed buffer as
against deflate which does not hold the size of the buffer, so
the decompression will be made in a static buffer.
This function requests no parameters.
WARNING: This function replaces the original buffer of the
message with the decompressed buffer, so any processing you do
to the message will not be taken into consideration. Try
applying the decompression function, before you do any other
processing to the message.
This function can be used from REQUEST_ROUTE, LOCAL_ROUTE,
FAILURE_ROUTE.
Example 1.5. mc_decompress usage
...
if (!mc_decompress())
xlog("decompression failed\n");
...
1.8. Compression performance test for sip messages
The following results have been obtained using the compression
function included in the module. Using this results, you can
improve the usage of this module, in order to compress only
when you think it is favorable enough for you. The algorithm
used is deflate for all cases because gzip is always 16 bytes
higher than deflate, which represents the uncompressed size
modulo 4GB. For the subtests in the same test, the same SIP
message have been used.
Table 1.1. mc_compress performance test results
Test Number Subtest Number Body Size Headers to Compress Size
Compressed Content Compressed Content Size Compression level
Compressed size Compression ratio
1 1 179 82 Body + Headers 261 1 284 0.91
1 2 179 82 Body + Headers 261 9 284 0.91
1 3 179 82 Body 179 1 196 0.91
1 4 179 82 Body 179 9 196 0.91
2 1 838 392 Body + Headers 1230 1 898 1.36
2 2 838 392 Body + Headers 1230 9 872 1.41
2 3 838 392 Body 838 1 568 1.47
2 4 838 392 Body 838 1 540 1.55
3 1 1329 607 Body + Headers 1936 1 1396 1.38
3 2 1329 607 Body + Headers 1936 9 1352 1.43
3 3 1329 607 Body 1329 1 840 1.58
3 4 1329 607 Body + Headers 1329 9 804 1.65
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. Ionut Ionita (@ionutrazvanionita) 49 12 3976 192
2. Razvan Crainea (@razvancrainea) 32 20 283 518
3. Liviu Chircu (@liviuchircu) 6 4 15 31
4. Vlad Patrascu (@rvlad-patrascu) 6 4 8 11
5. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 3 1
6. Julián Moreno Patiño 3 1 2 2
7. Peter Lemenkov (@lemenkov) 3 1 1 1
8. Ryan Bullock (@rrb3942) 2 1 1 0
9. Zero King (@l2dy) 2 1 0 5
(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. Razvan Crainea (@razvancrainea) Dec 2014 - Jul 2020
2. Zero King (@l2dy) Mar 2020 - Mar 2020
3. Liviu Chircu (@liviuchircu) Apr 2018 - Aug 2019
4. Vlad Patrascu (@rvlad-patrascu) May 2017 - Apr 2019
5. Bogdan-Andrei Iancu (@bogdan-iancu) Dec 2014 - Apr 2019
6. Ryan Bullock (@rrb3942) Mar 2019 - Mar 2019
7. Peter Lemenkov (@lemenkov) Jun 2018 - Jun 2018
8. Ionut Ionita (@ionutrazvanionita) Nov 2014 - Nov 2016
9. Julián Moreno Patiño Feb 2016 - Feb 2016
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu
(@rvlad-patrascu), Razvan Crainea (@razvancrainea), Peter
Lemenkov (@lemenkov), Ionut Ionita (@ionutrazvanionita).
Documentation Copyrights:
Copyright © 2014 Voice Sistem SRL
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。