updates for patch that came in just under the wire
[OpenSRF.git] / doc / RELEASE_NOTES.txt
1 Release notes for OpenSRF 2.5.0
2 ===============================
3
4 Supported platforms
5 -------------------
6 The following Linux distributions are well-tested:
7
8   * Debian 7 (Wheezy) and 8 (Jessie)
9   * Ubuntu 14.04 (Trusty Tahr) and 16.04 LTS (Xenial Xerus)
10
11 New features in 2.5.0
12 ---------------------
13
14 Chunking and bundling (LP#1612771)
15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17 Message Bundling and Chunking
18 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
19
20 OpenSRF now supports message chunking, i.e., breaking up large OpenSRF
21 messages across multiple XMPP envelopes. This is implemented with a
22 new OpenSRF message type.
23
24 C, Perl, and Javascript libraries are taught how to reconstruct chunked
25 messages. The default chunking threshold is 50Kb, just a bit below the
26 default ejabberd max stanza size of 64Kb.
27
28 What was previously called chunking is now referred to as bundling:
29 packing multiple OpenSRF messages together in a single XMPP envelope,
30 as long as we believe more messages will be sent in the future and we
31 are below some threshold of combined message size.  The default for
32 that threshold is 25Kb.
33
34 With this change, it is no longer necessary to change the `max_stanza_size`
35 setting for ejabberd when installing OpenSRF.
36
37 Pass client timezone to server (LP#1485371)
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39
40 OpenSRF has long inspected the envelope of incoming requests for information
41 about the client's locale and made this information available to business
42 logic.  This is used, among other things, to drive transparent translation of
43 in-database strings within Evergreen.  In addition to locale, OpenSRF will
44 now respect client-supplied adjustment to the effective time zone in which it
45 operates, and provide that information to the business logic layer of
46 applications built on the framework.
47
48 Client
49 ^^^^^^
50
51 As most clients that have time zones which differ from that of the server on
52 which the OpenSRF processes run are, in fact, web browsers, it is necessary
53 to include time zone detection directly within the browser.  This will be
54 stored in a cookie to be sent with all subsequent HTTP requests, and used in
55 all OpenSRF-over-HTTP calls made using the JavaScript bindings for OpenSRF,
56 including those for WebSockets communication.
57
58 For non-browser clients, such as support scripts written in Perl or other
59 scripting languages, the local system's mechanisms for detecting time zone
60 is relied upon.  For instance, Perl scripts can directly read the TZ
61 environment variable.
62
63 Additionally, the srfsh client now reads its local time zone from the
64 environment and passes that to the server. 
65
66 Server
67 ^^^^^^
68
69 Within OpenSRF services implemented in Perl, this information is now passed up
70 to the business logic layer via the TZ environment variable, and is reverted
71 to the server's value at the end of each request.  This allows automatic,
72 transparent use of the client's time zone in almost all cases, and provides a
73 system-normal access mechanism when direct access is required.
74
75 For OpenSRF services implemented in C, the time zone information is provided
76 as part of the request context object that is passed to implementation
77 functions.  In particular, this allows services that interact with a database
78 to set the time zone in which the database interprets timestamps to that of
79 the client.
80
81 Dispatch mode for method_lookup subrequests (LP#1631522)
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84 There is a pattern in the wild of using OpenSRF's `method_lookup()` facility
85 to decide between one of several local methods when delegating to pre-existing
86 logic.  Often times, we want to simply hand control over to another method,
87 but the output of a subrequest's `run()` is an array of results.  The caller has
88 to know if, and how, to restructure the result for the client.
89
90 Instead, we can now call `dispatch()` instead of `run()` and have OpenSRF session
91 control completely passed to the delegate code.  This way, the delegate code
92 need not know anything about its caller, and vice versa.
93
94 Example proxy server configurations (LP#1638651, LP#1648188, and LP#1666706)
95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96
97 OpenSRF 2.5 comes with example configurations for using HAProxy or
98 NGINX as a reverse proxy for HTTP, HTTPS, and WebSockets traffic. This
99 can be useful for Evergreen systems that wish to use port 443 for both
100 HTTPS and secure WebSockets traffic.
101
102 Along with the example configuration files, there is now a new configure option,
103 `--with-websockets-port`, to allow installers to specify the WebSockets port
104 that JavaScript clients should use.
105
106 Allow admin to specify where perl modules will be installed (LP#1631520)
107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108 Add `--with-perlbase` option to the `configure` to specify
109 an alternative location for installing the Perl modules. This
110 can be useful for setups that want to run the Perl modules
111 from a shared filesystem or environments that need to run
112 multiple versions of OpenSRF simultaneously.
113
114 Users of `--with-perlbase` are responsible for ensuring that
115 `PERL5LIB` is set appropriately.
116
117 Other changes
118 -------------
119
120   * Drop support for Debian Squeeze (LP#1559121)
121   * Drop support for Ubuntu Precise (LP#1603708)
122   * Add support for Ubuntu Xenial (LP#1551090)
123   * Fix a bug with syslog configuration (LP#1473479)
124   * Fix OpenSRF debian_sys_config order for Debian (LP#1585041)
125   * Improvements to the installation documentation (LP#1382038, LP#1670045, and LP#1672926)
126   * Improve normalization of memcache keys to avoid potential
127     denial of service and privilege escalation attacks. (LP#1652382)
128   * Fix an infinite recursion bug in opensrf.system.method.all. (LP#1652122)
129   * Propagate bundling/chunking limits to subrequests. (LP#1655449)
130   * Add a way for mod_perl handlers that are OpenSRF clients
131     to detect when the web browser has disconnected, and in turn stop listening
132     for results from XMPP requests pending when the browser disconnect
133     happened. (LP#1616501)
134   * Remove Fedora from the list of well-tested platforms. The
135     installation target for Fedora still exists, but needs work.
136   * The default configuration files shipped with OpenSRF
137     no longer include support for insecure WebSockets. (LP#1667091)
138
139 Acknowledgements
140 ----------------
141
142 We would like to thank the following people who contributed to OpenSRF 2.5.0:
143
144   * Ben Shum 
145   * Bill Erickson 
146   * Chris Sharp 
147   * Dan Scott
148   * Galen Charlton 
149   * Jason Etheridge 
150   * Jason Stephenson 
151   * Jeff Davis
152   * Kathy Lussier
153   * Mike Rylander 
154   * Remington Steed