doc/RELEASE_NOTES.txt

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