doc/RELEASE_NOTES.txt

   1 OpenSRF 3.1-beta
   2 ----------------
   3 OpenSRF 3.1-beta was released on 9 January 2019. This is a major
   4 release adding several new features and fixing serveral bugs.
   5
   6 New Features and Major Bugfixes
   7 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   8
   9 Support for Websocketd (LP#1777180)
  10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  11 OpenSRF 3.1 adds support for https://github.com/joewalnes/websocketd[websocketd]
  12 as a backend providing a WebSocket gateway for OpenSRF requests.
  13 `websocketd` offers significant reliability improvements over Apache's
  14 `mod_websocket`, which is no longer recommended for production use.
  15
  16 Request Backlog Queues (LP#1729610)
  17 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  18 Perl and C service listeners now have the ability to queue requests
  19 that cannot be immediately handled because no drones are available.
  20 This allows services to handle transitory spikes in incoming requests
  21 while conserving expensive resources such as database connections.
  22
  23 The request backlog queue is used when a service has reached the drone
  24 count set by its `max_children` setting and all of its drones are
  25 handling other requests. The backlog queue is FIFO, so Once a drone
  26 becomes available, it will process the oldest queued request.
  27
  28 Each service's backlog queue can contain 1,000 requests by default;
  29 this limit can be adjusted using the `max_backlog_queue` service
  30 setting.
  31
  32 If the backlog queue would grow beyond its limit, incoming requests
  33 that would be added to it are instead dropped. When a request
  34 is dropped, an OpenSRF method exception response is sent back
  35 to the client. This exception has a status code of 503 ("service
  36 unavailable") and is provided to give clients the opportunity to
  37 pause sending requests or display a useful error message to the
  38 user.
  39
  40 This feature includes two new example services, `opensrf.cslow` and
  41 `opensrf.slooooooow`, written in C and Perl respectively. Both services
  42 have a "wait" method that waits for a specified number of seconds, then
  43 returns that number. These services can be used for testing the backlog
  44 queue and simulating long-running methods during performance testing
  45 of OpenSRF applications.
  46
  47 Ability to Force-Recyle Drones (LP#1706147)
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49 Perl applications now allow a method to indicate that the drone
  50 running it be recycled upon completion of that method. This allows
  51 methods that are known to require a long time to run or consume
  52 (or leak) significant amounts of memory to force system resources
  53 to be returned upon completion.
  54
  55 Perl methods that wish to force drone-reycling can do so like this:
  56
  57 [source,perl]
  58 ----
  59 sub some_api_method {
  60     my ($self, $client, ...) = @_;
  61     $self->session->force_recycle(1);
  62     ...
  63 }
  64 ----
  65
  66 Changes to Supported Linux Distributions (LP#1793585 and LP#1718459)
  67 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  68 Support for Ubuntu 18.04 "Bionic Beaver" has been added, while support
  69 for Debian Wheezy has been dropped.
  70
  71 Users of Ubuntu 14.04 ("Trusty Tahr") should note that Trusty will
  72 reach end of life in April 2019 and that OpenSRF support for
  73 Tahr will end in a subsequent release in the 3.1.x series.
  74
  75 Support Modern Ejabberd (LP#1703411)
  76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  77 Modern versions of Ejabberd strip custom XML attributes which appear
  78 outside of custom elements.  To support OpenSRF's custom router and
  79 osrf_xid commands, these attribute are now moved into a new custom XML element
  80 `<opensrf>`.
  81
  82 Improved Example NGINX Configuration (LP#1711145)
  83 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  84 The example NGINX reverse proxy configuration file that ships with
  85 OpenSRF is significantly improved:
  86
  87 * Implements HTTPS security recommendations from Mozilla
  88 * Enables http2
  89 * Applies a 5-minute proxy read timeout to avoid too-short timeouts on
  90   long API calls.
  91 * Adds a (commented) section on sending NGINX logs to syslog
  92
  93 OpenSRF HTTP Translator Can Now Access User Agent IP Address (LP#1684970)
  94 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95 The OpenSRF HTTP translator can now obtain the user agent's IP address
  96 (as opposed to the IP address of the proxy) when running behind a
  97 reverse proxy. This fixes a problem where it is theoretically possible
  98 for two clients to access the same OpenSRF worker process over the
  99 HTTP translator. This also fixes a problem where proxied requests
 100 could various see the IPv4 and IPv6 forms of the proxy's address,
 101 potentially breaking long-running transactions made through the
 102 translator.
 103
 104 This fix requires use of the `mod_remoteip` Apache module.
 105
 106 Other Bugs Fixed
 107 ^^^^^^^^^^^^^^^^
 108 * The JavaScript client library now detects when a transport error
 109   occurs when making a WebSocket request and invokes either
 110   the transport or generic error handler, depending on what has
 111   been set by the client. (LP#1776510)
 112 * OpenSRF could fail to retrieve memcached values whose keys contain
 113   the % character. This resulted in breaking authentication in
 114   Evergreen when the username or barcode contained a %. (LP#1684970)
 115
 116 Upgrade Notes
 117 ~~~~~~~~~~~~~
 118 OpenSRF 3.1 introduces changes to the application binary interface
 119 (ABI) for C applications. Consequently, Evergreen users should plan on
 120 recompiling Evergreen after installing OpenSRF 3.1.
 121
 122 Users of NGINX should review the `examples/nginx/osrf-ws-http-proxy`
 123 example configuration file and make adjustments to their example
 124 configuration accordingly, including generating a new DH Group
 125 using the `openssl dhparam` command.
 126
 127 Users of a reverse proxy such as NGINX should install and enable
 128 the Apache `mod_remoteip` module, then adjust the Apache configuration
 129 to include lines like this:
 130
 131 [source]
 132 ----
 133     RemoteIPInternalProxy 127.0.0.1/24 # or whatever the proxy IP address is
 134     RemoteIPInternalProxy ::1          # or whatever the proxy IP address is
 135     RemoteIPHeader X-Real-IP
 136 ----
 137
 138 Note for Evergreen Users
 139 ~~~~~~~~~~~~~~~~~~~~~~~
 140 OpenSRF 3.1 can be used by Evergreen 3.0.x, 3.1.x, and 3.2.x.
 141
 142 Acknowledgements
 143 ~~~~~~~~~~~~~~~
 144
 145 We would like to thank the following people who contributed to OpenSRF 3.0.0:
 146
 147   * Galen Charlton
 148   * Jeff Davis
 149   * Bill Erickson
 150   * Mike Rylander
 151   * Chris Sharp
 152   * Ben Shum
 153   * Remington Steed
 154   * Jason Stephenson