_          _                   _
  __| |o ___ __| |__ ___  __ _  ___| |__   ___     distcache
 / _` |_/ __|__   __/ __|/ _` |/ __| '_ \ / , \    Distributed session caching
| (_| | \__ \  | | | (__| (_| | (__| | | |  __/    www.distcache.org
 \__,_|_|___/  |_|  \___|\__,_|\___|_| |_|\___|    distcache.sourceforge.net

-------------------------------------------------------------------------------

                                      ``It is not necessary to change. Survival
                                        is not mandatory.''
                                                         -- W. Edwards Deming


Current version: 1.5.1
----------------------


Changes between 1.5.0 and 1.5.1
-------------------------------

  *) Add a new 'nal_proxy' application. This configures various address pairs
     from the command-line and will then accept connections on all the ingress
     addresses and make outbound connections on the egress addresses. Traffic
     is forwarded until either side disconnects.
     [Geoff Thorpe]

  *) Add another libnal test, nal_pong, that plays request/response
     transactions with configurable sizes. It doesn't check payloads, and
     requires clients and servers to be set up with matching parameters, but
     provides a useful way to run asymmetric traffic tests.
     [Geoff Thorpe]

  *) Turn nagle off (ie. set TCP_NODELAY) by default on sockets. The IO models
     we use typically results in good defragmentation anyway and nagle adds
     unnecessary delay.
     [Geoff Thorpe]

  *) Add a "speed" mode to nal_ping that initialises an outgoing packet once
     only and doesn't memcmp() any responses.
     [Geoff Thorpe]

  *) Factor out nal_echo's timing code into a header, timing.h, and add the
     same support to the nal_ping client.
     [Geoff Thorpe]

  *) Fix up nal_echo's timing mechanisms and command-line processing for
     "-units". It can now report (kilo/mega/giga) bits or bytes per second.
     [Geoff Thorpe]

  *) Add a new test tool, "nal_hose", for use as an alternative to nal_ping.
     The new tool allows each connection to have more than one chunk of data in
     flight whilst waiting for responses from the echo server - this is
     controlled by a "-lag" command-line switch. Also, the chunks each have a
     8-byte header, that uniquely determine the rest of data as well as the
     index of the chunk itself. This allows it to congest a lot of outgoing
     data into the network without needing to maintain state to handle the
     responses later.
     [Geoff Thorpe]

  *) Add "-update" and "-units" command-line switches to nal_echo to allow
     traffic and CPU usage to be monitored. See the usage output for more
     details ("nal_echo -?").
     [Geoff Thorpe]

  *) Add a return code to the (previously void) API function
     NAL_BUFFER_transfer() to return the amount of data transfered.
     [Geoff Thorpe]

  *) Add the beginnings of ssl library support in ssl/libnalssl. This builds
     and installs a libnalssl.a library and the libnal/nal_ssl.h header.
     Currently, this is just a BIO wrapper for NAL_CONNECTION (which is
     strictly speaking not even SSL related, but whatever).
     [Geoff Thorpe]

  *) Add a new "dynamic" selector type as the default that allows a listener
     or connection implementation to set it on-the-fly to the kind of selector
     it requires. This is (of course) only a first-use initialisation, after
     which the selector is fixed, but obviates the need for using other
     mechanisms, such as environment variables, to specify at run-time which
     I/O model is required for the protocols that will be in use.
     [Geoff Thorpe]
 
  *) Add "pre_close" handlers to the libnal vtable types to allow
     implementations to perform actions prior to being destroyed or reset.
     Their existing "on_destroy" and "on_reset" handlers are invoked during
     cleanup so can't assume that data outside their control hasn't been
     changed (eg. the relationship between listeners or connections and a
     selector).
     [Geoff Thorpe]

  *) Add a NAL_SELECTOR_num_objects() API function (and corresponding vtable
     entry) to have selectors report how many listeners/connections are
     attached. Eventually, programs should use this as a safe termination
     condition for event loops (with corresponding use of NAL_LISTENER_finished
     where appropriate). For example, this will permit asynchronous closes. The
     main obstacle for the latter is that NAL_[LISTENER|CONNECTION]_free() are
     synchronous calls, so any asynchronous overhang could be migrated into the
     selector object itself. Note, none of the programs/utilities support any
     of this yet.
     [Geoff Thorpe]

  *) Allow "-Werror" to be set in CFLAGS without it causing configuration to
     fail due to sloppy autogenerated tests. This is achieved using what is
     probably a Bad(tm) mechanism - "-Werror" is removed from CFLAGS before
     autoconf tests and replaced later before generating configuration output.
     [Geoff Thorpe]

  *) - Add a "-errinject" switch to nal_echo to have it insert 0xdeadbeef into
       output periodically. (Oh, and ignore sigpipe too!)
     - Add a "-mode" switch to nal_ping to control the type of data sent in the
       ping packets (choices: 'zero', 'block', or 'noise').
     - Have nal_ping display a full hexdump of send and receive packets when an
       error is detected.
     - Add "-peek" and "-quiet" switches to nal_ping to control the level of
       output. The former will print the first 8 bytes of every packet sent and
       received. The latter will surpress "Packet n ok" messages and error
       hexdumps.
     [Geoff Thorpe]

  *) Fix dc_client to call setuid() after it has written its pid file.
     [Joe Orton]

  *) Fix a bug in the poll() wrapper to not "detect" errors at the same time as
     a data read or write event. Otherwise we can lose incoming data by seeing
     the disconnection that's behind it.
     [Geoff Thorpe]

  *) Fix sslswamp to work with the new libnal model.
     [Geoff Thorpe, Joe Orton]

Changes between 1.4.4 and 1.5.0
-------------------------------

  *) The memory functions used in the case SYS_DEBUG_LEVEL is set high were
     violating the linker rules I'd put in place, so I'm ditching this needless
     indirection. I've also removed the debug stream functions - the current
     use of macros allows indirection later if we need it. Add a new script for
     sanity checking - this ensures code is using "SYS_" wrapper functions (or
     macros) than the underlying system functions.
     [Geoff Thorpe]

  *) Connections and listeners now have both pre and post hooks for binding
     to and unbinding from selectors.
     [Geoff Thorpe]

  *) Added implementation-specific constructors for NAL_SELECTORs, allowing
     poll() or select() to be chosen as desired.
     [Geoff Thorpe]

  *) Replaced the fd_set/fd_test callbacks from the NAL_SELECTOR_vtable
     interface with a more general-purpose "ctrl" handler.
     [Geoff Thorpe]

  *) Add two new test programs, "nal_echo" and "nal_ping". The former is a
     simple server program that manages (up to) some configurable number of
     incoming connections, echoing all received data back to the client. The
     latter manages a configurable number of outgoing connections, in each one
     looping a configurable number of times sending a configurably sized random
     packet and waiting for an identical response. This is primarily for libnal
     testing, but nal_echo in particular is a good illustration on programming
     with the libnal API.
     [Geoff Thorpe]

  *) A serious overhaul of the I/O model and the NAL_SELECTOR type that
     underpins it has been made. Previously this was a very select()-like
     storage object on which an application loop would; (a) add all listeners
     and connections, (b) block via NAL_SELECTOR_select(), and (c) call I/O
     functions for all objects by providing the NAL_SELECTOR object to specify
     I/O state.
     
     Under the new model, listeners and connections are either bound to a
     selector object or unbound (but may not bind to more than one) - so once
     'added' to a selector they remain bound until explicitly removed or
     destroyed. This step allows the connection/listener implementations to
     veto the binding if the selector implementation is incompatible. This is
     intended to allow alternative I/O models and objects to be supported
     without requiring them all to be necessarily interchangable, and handling
     this during the binding step obviates the need to perform such checks
     inside I/O loops (and also allows implementations to pre-cache useful
     information based on the type of selector it is binding to). During the
     NAL_SELECTOR_select() call, all listeners and connections are given a
     'pre_select' hook to prepare any I/O criteria (with the select()
     implementation, this amounts to FD_SET() - whereas other models may
     involve changing message handlers for given events, etc). Then after the
     blocking, NAL_SELECTOR_select() may invoke a 'post_select' hook on any
     objects that have I/O activity. None of this is exposed to the caller,
     instead they can continue to use the NAL_LISTENER_accept() or
     NAL_CONNECTION_io() functions, but these no longer involve any genuine I/O
     and so are purely for post-processing, error handling, etc.

     The libnal API now has been simplified as a result (and some unnecessary
     and unused extensions removed). In particular, the binding between objects
     now means many functions no longer take a NAL_SELECTOR pointer parameter.
     There is also a second selector implementation based on poll() to
     complement the existing (though modified) one based on select().  If both
     are supported, then poll() is used by preference unless "--disable-poll"
     is specified to the configuration script.
     [Geoff Thorpe]

  *) A somewhat serious race bug has been uncovered in the 'dc_client' utility
     used to proxy distcache operations between applications and a remote
     server. The multiplexing code that handles rewriting request uids was
     horribly broken when cleaning up after a disconnected client, and would
     cause all requests on other client connections to be orphaned. The fact
     this hasn't been discovered before is largely due to lucky timing, but
     would almost certainly cause instabilities long term in any real-world
     deployment. Upgrading is highly recommended, and apologies that such a
     wild bug has managed to slip through my testing this long, I'm somewhat
     stunned myself!
     [Geoff Thorpe]

  *) Make NAL_SELECTOR vtable-based like NAL_ADDRESS, NAL_LISTENER, [etc]. The
     main difference between the others is that there is no "create()" step
     after allocating the structure with NAL_SELECTOR_new() - a default vtable
     is automatically chosen. This allows existing code to compile and run as
     before, but facilitates the side-use of alternative selectors by using
     different constructors.
     This also adds NAL_SELECTOR_reset() to the API.
     [Geoff Thorpe]

  *) Created CVS branch "BRANCH_1_4", this is the first commit to the CVS head
     since then. Some libnal development and rewirings are in the works to
     support alternative I/O models, so BRANCH_1_4 exists for maintenance
     releases with the intention of this branch producing the "stable" releases
     (eventually deprecating 0.4).
     [Geoff Thorpe]

  *) Minor restructuring in NAL_SELECTOR to more cleanly separate between the
     API and the underlying details.
     [Geoff Thorpe]

Changes between 1.4.3 and 1.4.4
-------------------------------

  *) Replace configure.ac with configure.ac.template in the ssl/ subdirectory
     so that the bootstrap.sh script can (re)create the autoconf script more
     easily. This is to ensure the version information from the top-level
     configure.ac script is replicated into the sub-directory's script.
     [Geoff Thorpe]

  *) Ensure that the default behaviour is to built static libs and no shared
     libs. Specifying --disable-static and/or --enable-shared to the configure
     script can override this behaviour. Reword the help strings in the
     configure script to be "--disable-..." when the feature in question is
     on by default. Also, use autoconf to define (or not, as the case may be)
     optional sub-directories to the Makefile.in->Makefile conversion rather
     than using automake conditionals in the Makefile.am->Makefile.in process.
     This fixes a build error in 1.4.3 that would configure ssl targets but
     not build or install them.
     [Geoff Thorpe]

  *) Minor documentation improvements.
     [Geoff Thorpe]

  *) Add a new switch "-sslmeth <meth>" to the 'sslswamp' tool to allow the
     user to stipulate the record and handshake layer version required. Apart
     from fixing the record layer version in advance, this switch is also the
     easiest way of avoiding the use of SSLv2-compatible ClientHello records.
     The values for "<meth>" are "normal", "sslv2", "sslv3", and "tlsv1".
     [Geoff Thorpe]

Changes between 1.4.2 and 1.4.3
-------------------------------

  *) Fix a bug that can cause non-blocking connects to jam. If a non-blocking
     connect begins, the appropriate way to spot completion (or failure) is by
     selecting for writability, but this was not necessarily happening. Worse
     still, the application can go into an infinite loop with select() breaking
     because of readability despite the fact that the read IO logic was not
     checking for nb-connect completions (this happens only in the send IO
     logic). The cleanest way is to not select for readability until the
     connect is complete, though an alternative would be to duplicate the
     completion checking code for the read case too - I'll stick with this one
     for now.
     [Geoff Thorpe]

  *) Add "-sockowner", "-sockgroup", and "-sockperms" command-line switches to
     dc_server and dc_client to allow ownership and permission controls when
     listening on unix domain sockets. On most systems, these would only
     succeed when starting programs as root (in which case, the "-user" switch
     would be wise too). If autoconf is unable to build support for these
     options, they will always emit failure warnings at run-time before
     continuing.
     [Geoff Thorpe, based on an idea/patch from Joe Orton <jorton@redhat.com>]

  *) Add chown/chmod support to libnal listener objects via two new API
     functions;
       NAL_LISTENER_set_fs_owner();
       NAL_LISTENER_set_fs_perms();
     When creating listener objects over unix domain sockets, the ownership and
     permissions can be altered to control connection access. (Note, this
     usually requires root permissions.) This functionality uses two new
     handlers added to the listener vtable type, and listener types that do not
     support this functionality (TCP/IP, "FD:" pipes, [etc]) supply NULL
     handlers and the API will return errors on their behalf.
     [Geoff Thorpe, based on code from Joe Orton <jorton@redhat.com>]

  *) Add setuid support to libsys as SYS_setuid(), corresponding tests in
     configure.ac, and add a corresponding "-user <user>" command-line switch
     to dc_server and dc_client.
     [Joe Orton <jorton@redhat.com>]

  *) In the last release, certain functions operating on selectors and
     connections or listeners were changed from being NAL_SELECTOR_***
     functions to NAL_[CONNECTION|LISTENER]_*** equivalents. Unfortunately,
     this change lost the ability to add connections to listeners with a
     bitwise flag allowing the caller to stipulate which events (s)he wants
     selected (or more accurately, which events (s)he does *not* want
     selected). This has been reinserted in the underlying libnal vtable
     layouts, and the new API function NAL_CONNECTION_add_to_selector_ex()
     exposes this extension.
     [Geoff Thorpe]

Changes between 1.4.1 and 1.4.2
-------------------------------

  *) Add a new shell tool called "piper" to help support and test
     file-descriptor based addresses. This code is in a new directory, "util/".
     'piper' lets you start two commands as child-processes with arbitrary
     pipes between them. The default pipe, "--", is equivalent to "--1>0,0<1"
     which means to bind stdin/stdout to each other between the two commands (a
     bidirectional version of the traditional pipe '|'). The code is ugly, and
     it could probably benefit with being overhauled and generalised (eg.
     chaining more than two commands, allowing pipes from the last command to
     the first, etc). However, right now it works and lets you do things like;

        piper dc_test -connect FD:0:1 -persistent -- dc_server -listen FD:0:1

     [Geoff Thorpe]

  *) Reinstate the NAL_CONNECTION_create_pair() function in the new vtable
     code (as its an API function to the socket-specific vtables).
     [Geoff Thorpe]

  *) Add a new address/listener/connection family based on arbitrary
     file-descriptors. The syntax for these types are FD:<num> for a single
     descriptor for reads and writes, or FD:<n1>:<n2> for different read and
     write descriptors. The semantics are that connections work immediately
     without opening anything, but close the corresponding descriptors when
     cleaning up (this should be configurable in the syntax at some point).
     Listeners of this form accept a connection on the first given chance, but
     thereafter are marked "finished", as noticed by NAL_LISTENER_finished().
     Also that read-only or write-only connections can be created using -1 as a
     file-descriptor in one half of the syntax.
     [Geoff Thorpe]


  *) To support a more general class of network abstractions, is makes sense to
     consider the possibility of a listener terminating. The pressing example
     that I'm working on is a file-descriptor address type that would support,
     for example, specifying stdin/stdout as an address for use in pipes and
     what-not. In such a case, "listening" on stdin/stdout amounts to accepting
     a single connection - and the most logical way to phrase this in the API
     is to consider that the listener is "finished" once it has accepted a
     single connection object (which it will gladly do at the first given
     chance). So NAL_LISTENER_finished() has been added, with the appropriate
     vtable wiring in libnal.
     [Geoff Thorpe]

  *) Add a NAL_BUFFER_transfer() function for automatically moving as much data
     as possible from one buffer to another.
     [Geoff Thorpe]

  *) Adjust the vtable design in libnal to make things more orthogonal. As part
     of this, each vtable has a parameterless constructor that is used in
     advance of any other "create" handlers. From the libnal API, these are
     usually seen as a single function, but separating them internally allows
     the "reset" logic to work better. This also exposes a consistent set of
     vtable functions in nal_devel.h to let vtable implementations manipulate
     libnal objects directly.
     [Geoff Thorpe]

  *) Created a new exported header, <libnal/nal_devel.h>, containing elements
     split out from libnal's own nal_internal.h header. This header can be used
     to implement additional network abstraction types.
     [Geoff Thorpe]

  *) Allow NAL_ADDRESS_vtable implementations to register themeselves with the
     libnal core so they become automatically available to applications via
     their string syntax. As with the builtin (IPv4/UNIX) vtable
     implementation, this provides the single point of entry to any associated
     implementations of listener and connection types.
     [Geoff Thorpe]

  *) Compact the AC_CHECK_*** macros so we save space in the generated
     configure scripts.
     [Joe Orton]

  *) Adjusted the NAL_[ADDRESS|LISTENER|CONNECTION] vtable handling in libnal
     so that the API instantiates contexts on behalf of implementations. Apart
     from simplifying implementation code (their contexts are always there so,
     there's no allocation and error handling required), this will also make it
     easier to introduce object reuse.
     [Geoff Thorpe]

  *) Added the beginnings of a benchmarking and self-testing libnal program,
     nal_test.
     [Geoff Thorpe]

  *) Modularisation of libnal (sequel to the earlier overhaul)
     - the major libnal types are now abstract classes implemented via vtables
       with interfaces defined in nal_internal.h.
     - the IPv4 and UNIX transports are handled by the same vtable
       implementation, in proto_std.c, by developing and making more use of the
       nal_sockaddr wrapper in util_socket.c.
     - The libnal API functions are implemented independantly of the vtable
       implementations they defer to, and are separated into the following C
       files; nal_address.c, nal_buffer.c, nal_connection.c, nal_listener.c, and
       nal_selector.c. nal_codec.c contains the primitives-serialisation
       functionality that used to be in bincoding.c.

     This new code seems to break nothing but it may (of course) have introduced
     bugs. It may also have introduced some slow-downs due to the more
     abstracted and formal approach - I've deliberately put off a bunch of
     optimisations until I get this working. I will be committing some libnal
     testing code shortly.

     The overhauling of the API is not finished yet - some generalisation of
     NAL_BUFFER is required (it is currently not abstracted like the other
     types), and once the code settles down again I will look at some header
     reorganisations so that the necessary "internal" elements of the libnal
     headers can be exposed to facilitate external plugin implementations.
     [Geoff Thorpe]

  *) Add a "-killable" switch to dc_server and dc_client so that SIGUSR1 or
     SIGUSR2 cause a clean shutdown, for memory leak checking mainly. However
     to make this sane from a user/admin point of view, we make them *ignore*
     either signal if the switch is not specified (rather than the default
     behaviour which is to automatically terminate the process).
     [Geoff Thorpe]

  *) Added a SYS_sigusr_interrupt() function to the libsys API for use by
     executables (can't be added to libraries). The normal response to a
     SIGUSR1 or SIGUSR2 signal is to kill the process immediately, but by
     handling this signal with a callback the effect is that any
     NAL_SELECTOR_select() operation is interrupted with a negative return
     value. NB: If the signals are SIG_IGN'd instead, the select doesn't break
     (on linux at least), so a handler callback is required. To handle the case
     that the signal arrives while we're not sleeping, a pointer (int *) is
     passed that will be set to non-zero from the signal handler.
     [Geoff Thorpe]

  *) Improved cleanup code in dc_test (for memory leaks).
     [Geoff Thorpe]

  *) Major overhaul of libnal
     - NAL_BUFFER implementation separated out into buffer.c
     - NAL_SELECTOR implementation separated out into selector.c
     - addition of NAL_LISTENER_get_fd()
     - addition of const versions of NAL_CONNECTION_get_[read|send]
     - converted NAL_SELECTOR_[add|del]_[conn|listener] functions into
       NAL_LISTENER_*** and NAL_CONNECTION_*** equivalents.
     - converted NAL_LISTENER_accept() to NAL_CONNECTION_accept() as this makes
       more OO sense. Also removed NAL_LISTENER_accept_block() which was unused
       (and trivial for the caller to manufacture if they need it).
     - removed NAL_[CONNECTION|LISTENER]_get_fd() functions as these don't
       help me to preserve opacity and weren't used (except to work around
       the problem now solved by the previous change in this list).
     - removed unused "mask"ing from the libnal-internal "unset/clear"
       functions - unecessary complexity.
     - updated documentation for the above changes and tried to improve
       clarity in the process.
     - NAL_CONNECTION now dynamically allocates its NAL_BUFFER buffers.
     - file-descriptor work is now handled in util_fd.c, and functions are
       called nal_fd_*** instead of int_***.
     - socket work is now handled in util_socket.c, and functions are called
       nal_sock_*** instead of int_***.
     - int_check_buffer_size() is now nal_check_buffer_size.
     - libnal's internal sockaddr_safe type is now nal_sockaddr.
     - nal_sock_sockaddr_from_ipv4() now handles name resolution and other
       aspects of address parsing, removing complexity from NAL_ADDRESS code.
     - NAL_LISTENER and NAL_CONNECTION no longer keep an internal copy of their
       parent NAL_ADDRESS structures. This makes encapsulation hard, has never
       been used, and can be managed by the caller if they so wish (ie. if they
       want to keep a copy of the address, they can).
     - NAL_config_set_nagle() needs no return type, so it's now void.
     - NAL_ADDRESS_source_string() has been removed as this is as unnecessary
       as keeping a NAL_ADDRESS copy inside NAL_LISTENER and NAL_CONNECTION
       was - the caller can take care of such "caching" if they want/need it.
     - specialised functions (NAL_CONNECTION_create_[pair|dummy],
       NAL_SELECTOR_stdin_[add|readable], and NAL_stdin_set_non_blocking) have
       been "#if 0"'d out for the moment as they're unused and will (initially)
       complicate modularisation of the libnal implementations. I'll put these
       back in as/when I get round to it after I'm done with the current
       overhauls.
     - minor tidy-ups and bug-fixes
     [Geoff Thorpe]

  *) Put libtool in charge of compilation and linking again and, by default,
     build shared libraries again. For development purposes, the bootstrap
     script uses "--disable-shared" when PRECONF is being used.
     [Geoff Thorpe]

  *) Update copyright dates to 2003.
     [Geoff Thorpe]

  *) Some minor bug fixes in sslswamp.
     [Geoff Thorpe]

Changes between 0.4 and 1.4.1 
-----------------------------

  *) Bundle CA.pem and A-client.pem into the sslswamp directory (and RPM). These
     are also installed in the appropriate location and the sslswamp executable
     is compiled to find CA.pem automatically.
     [Geoff Thorpe, with some Makefile.am hints from Steve Robb]

  *) Modifications to the RPM spec file;
     - Build sslswamp and package it in its own RPM file (distcache-sslswamp).
     - Use the "%configure" RPM macro rather than calling "./configure"
       directly. This ensures that per-platform optimisations and/or
       compilation preferences are honoured.
     - Pre-define $INSTALL_PROGRAM to automatically strip installed
       executables. I don't personally care about "GNU Coding Standards" that
       result in installed programs that are consistently 10 times bigger than
       they need to be, simple to add debugging information that would never be
       used by people who aren't capable of building programs themselves. Disk
       space and RAM are resources, and should not be abused.
     - Include instructions for building redistributable RPMs for various CPUs.
     [Geoff Thorpe]

  *) Change the top-level configuration such that the ssl/ tree is configured
     and built by default unless --disable-ssl is specified. Likewise, swamp
     is built by default unless --disable-swamp is specified.
     [Geoff Thorpe]

  *) Used AC_CONFIG_SUBDIRS to (conditionally) run the configure script in the
     ssl/ sub-tree. This is a more robust method for hooking up the build
     system, and solves the issue of automatically passing command-line flags
     to the other script (including appropriate changes for --srcdir, etc).
     [Geoff Thorpe, based on some salient wisdom from Steve Robb]

  *) Rename "swamp" to "sslswamp". This is to reduce the chances of name
     collisions with other non-ssl utilities, and to help the chances of
     sslswamp turning up on searches for ssl utilities.
     [Geoff Thorpe]

  *) An "ssl/" sub-tree has been created that includes its own autotools
     framework for building openssl-based utilities. The top-level build system
     handles;
     - selectively enabling the sub-tree's participation depending on the
       "--enable-ssl" switch.
     - synchronising the autoconf version number in ssl/ with that in the
       top-level distcache code.
     - Passing any ssl-specific configure switches through to the ssl/
       sub-tree's own configure script.
     - (un)bootstrapping the ssl/ sub-tree together with the top-level.
     Additionally, the latest release of swamp has been ported to use libnal
     and is included in the ssl/ sub-tree. Building of this ssl/tls
     benchmarking tool can be activated by specifying "--enable-swamp".
     [Geoff Thorpe]

  *) I will be creating a sub-tree for building SSL/TLS-dependant applications
     and this will start with the import of "swamp", a benchmarking program I
     want to unify with libnal. As part of this move, I'm bumping up the
     versioning system so that the next release will be 1.5 instead of 0.5. The
     reason for this is that swamp is currently at 1.1 and I want to avoid the
     inevitable confusion had swamp's version gone *down*. With this in mind,
     I've changed the autoconf script to set the version at 1.4.1dev and any
     pre-releases of 1.5 will be of the form 1.4.x (without the "dev" suffix).
     [Geoff Thorpe]

  *) I discovered a rather annoying bug in the 0.4 release just as I was
     updating apache-2 support. The s/NAL_/SYS_/ changes I made leading up to
     the 0.4 release caused some linker dependencies in our installed libraries
     upon libsys which is *internal-only*. The solution I have put in is that
     libsys/pre.h requires the C file to have declared SYS_LOCAL,
     SYS_GENERATING_EXE, or SYS_GENERATING_LIB. In the instance of
     SYS_GENERATING_LIB, libsys/post.h will not declare any functions
     implemented in libsys. Using this change, the offending dependencies were
     found and have been converted to macros.
     [Geoff Thorpe]

Changes between 0.4pre2 and 0.4
-------------------------------

  *) Added the ASCII-art from README.TOOLS to the FAQ so that README.API and
     README.TOOLS can been removed.
     [Geoff Thorpe]

  *) The headers have been re-organised to better guard against the possibility
     of API headers dependending on internal headers. To this end, the libsys
     header has been split in two - one header to include system headers based
     on autoconf findings (pre.h) and one to declare internal functions and
     macros used in the source code (post.h). API headers can depend on pre.h
     but not post.h. Likewise, distcache's internal header (dc_enc.h) has been
     renamed to dc_internal.h. Finally, all the C files have been checked to
     make sure they include headers in the correct order; (a) pre.h, (b) API
     headers, (c) miscellaneous internal headers, then (c) post.h.
     [Geoff Thorpe]

  *) The non-networking stuff in libnal (the daemon/sigpipe/etc wrappers as
     well as the mem and streams debugging cruft) has been separated out into a
     new library, libsys.a, that is not installed but is linked into the
     distcache executables. The names for these macros and functions have also
     been renamed from "nal" or "NAL" prefixes to "sys" and "SYS" respectively.
     Similarly, the source code has been moved out of the libnal/ directory
     into a new directory, libsys/, and the libnal/common.h header has been
     moved to libsys/sys.h.
     [Geoff Thorpe]

  *) Remove unnused stream-hacking functions from libnal, this should have been
     done when libnal first became a separately-installed library. I've also
     defined the NAL_fprintf and NAL_std[in|out|err] symbols directly to their
     stdio.h counterparts - they are only implemented when running debug
     builds, and this is so that we can undefine the raw stdio.h versions to
     verify our code isn't using them directly.
     [Geoff Thorpe]

  *) Force the use of alternative wrappers for strncpy and strdup because
     these may be defined as macros by the system that use memcpy and malloc
     and our debugging code shuts those off. As an added check, our strncpy
     wrapper macro null-terminates all strings unlike the normal version which
     can leave cropped strings without any terminator.
     [Geoff Thorpe]

  *) Fixed the NAL_CONNECTION_is_established() logic. Non-blocking connects are
     now handled and their eventual completion (or failure) will now break
     NAL_SELECTOR_select() operations. NAL_CONNECTION_is_established() and
     NAL_CONNECTION_io() now generate logical results for this scenario.
     [Geoff Thorpe]

  *) Re-organised the "devel/test.sh" script. Output is now cleaner and the
     script is easier to modify for customised mid-hacking tests.
     [Geoff Thorpe]

Changes between 0.4pre1 and 0.4pre2
-----------------------------------

  *) Replaced the "distcache.spec" RPM spec with "mandrake.spec.in". To work on
     non-Mandrake distributions probably requires changes anyway (as per the
     comments in the spec file). The use of autoconf to generate the spec file
     from mandrake.spec.in allows the appropriate version to be substituted
     automatically.
     [Geoff Thorpe]

  *) Forced "VERSION" to be defined by autoconf/automake by hacking inside
     configure.ac, and in such a way that "@VERSION@" is usable by Makefile.am
     files (eg. for pod2man, etc). This previously only worked reliably for the
     particular combination of autotool versions on my system.
     [Geoff Thorpe]

  *) The "targetgroup" replacement trick in the RPM spec was broken, so it has
     been ironed out and header comments have been expanded to note how to
     customise this for non-Mandrake RPM systems.
     [Geoff Thorpe]

  *) Produce conventional static-libraries directly rather than libtool
     archives. This is the easiest way to prevent the installation of "*.la"
     files and as we're already disabling building of shared-libraries
     (AC_DISABLE_SHARED in configure.ac), there's nothing to be gained from
     libtool libraries.
     [Geoff Thorpe]

  *) Allow CVS users to pass settings to bootstrap.sh for use in ./configure if
     it will be automatically run because of PRECONF. These settings can be
     specified by the PREFLAGS environment variable.
     [Geoff Thorpe]

  *) Documentation no longer builds or installs HTML files by default. These
     seem to have grief with cross-links and aren't much use. If someone
     decides to work on that at some point, we can always link it back in - but
     for the mean time the man pages provide the better format.
     [Geoff Thorpe]

  *) Many libnal functions had a return value merely to allow soft failure if a
     required parameter was NULL. This policy has been changed as a hard
     failure is guaranteed in such circumstances anyway and easier to diagnose
     at run-time. To simplify code and remove these unnecessary tests, the soft
     parameter checks have been removed and where appropriate, return types
     converted to void. These changes have propogated back through various
     dependant parts of the code and where appropriate, other functions have
     lost their return type if they are now guaranteed to succeed. Documents
     have also been changed where necessary.
     [Geoff Thorpe]

  *) The type-safe wrappers for malloc/realloc/free and memset/memcpy/memmove,
     as well as their replacement functions (only created during debug builds
     to verify that the raw functions aren't called), have been re-organised
     and consolidated. This results in one less function call each time for the
     malloc stuff in the non-debugging case, and more readable code.
     [Geoff Thorpe]

  *) Removed the unnecessary NAL_BUFFER_read_ptr() function as it is equivalent
     to NAL_BUFFER_data() except the latter (correctly) returns a const
     pointer. This function was apparently written when I was too distracted to
     realise that NAL_BUFFER is a FIFO and the read pointer is invariant. Also,
     remove the NAL_BUFFER_takedata() function and consolidate its slightly
     additional functionality into NAL_BUFFER_read() (namely that a NULL
     pointer can be used to turn the "read" into a "discard").
     [Geoff Thorpe]

  *) Add more API documents;
     - NAL_LISTENER_new.pod (all NAL_LISTENER functions)
     - NAL_SELECTOR_new.pod (all NAL_SELECTOR functions)
     - NAL_BUFFER_new.pod (all NAL_BUFFER functions)
     - NAL_decode_uint32.pod (all NAL_encode_*** and NAL_decode_*** functions)
     - DC_SERVER_new.pod (all DC_SERVER functions)
     [Geoff Thorpe]

Changes between 0.3 and 0.4pre1
-------------------------------

  *) Remove mention of README.API and README.TOOLS from the README, because
     they are not bundled into source distributions. Instead mention the
     documents contained in the doc/ directory.
     [Geoff Thorpe]

  *) More fixes to improve the usefulness of "make dist[-bzip2]";
     - a Makefile for ./devel/ to install useful files,
     - pod files in ./doc/ should be installed too,
     - BUGS note to remind us that README.API and README.TOOLS won't be
       installed and need to migrated to the man pages,
     - install extra files from the top-level directory (ANNOUNCE, BUGS,
       CHANGES, etc),
     - Update the top-level configure.ac to modern automake syntax and
       support for bzip2 tarballs,
     - use EXTRA_DIST in the includes/ directory for headers that aren't
       listed for installation.
     [Geoff Thorpe]

  *) Added a BUGS file, with an initial list of the bugs I'm aware of.
     [Geoff Thorpe]

  *) autoconf/automake-generated sludge files are now left in the top-level
     directory rather than having them in a config directory created and
     destroyed by (un)bootstrap.sh. This is because "make dist" is broken in at
     least one version of the tools and this is the only safe solution I can
     see.
     [Geoff Thorpe]

  *) Add more API documents, now for libnal;
     - NAL_ADDRESS_new.pod (all NAL_ADDRESS functions)
     - NAL_CONNECTION_new.pod (all NAL_CONNECTION functions)
     [Geoff Thorpe]

  *) Rename all libnal allocation functions to NAL_***_new() rather than
     NAL_***_malloc().
     [Geoff Thorpe]

  *) A top-level "include" directory has been created with sub-directories
     matching the format in which we install API headers. All header files that
     need to be used outside their own source directory have been moved into
     this tree, and the automake support has been added so that only those we
     wish to be treated as API will be installed. Eg. libdistcache/dc_enc.h
     needs to be used in a few directories but is not an API header so it has
     moved to include/distcache/ but will not be installed by automake. Ditto
     for libnal/common.h. A consequence of this is that our own source code now
     uses the same include paths as we document for users of the API, which is
     a "Good Thing". Also, we can refine the INCLUDES settings during building
     to be less loose than before. Previously the top-level directory would be
     available as an include path and so would the build directory. The latter
     was only needed to get to the autoconf-generated config/config.h file when
     building outside the source tree, and the former was to allow paths like
     libdistcache/ to be visible. For include paths, the top-level directory is
     now replaced by it include/" sub-directory, and the build directory is now
     replaced by its "config/ sub-directory.
     [Geoff Thorpe]

  *) dc_enc.h has been made an internal-only header and the parts of it we want
     exported have been moved to a new exported header, dc_plug.h. This hides
     DC_MSG and other protocol details from the API, which reduces the hassle
     involved in changing any of them later.
     [Geoff Thorpe]

  *) Start adding API section 2 man pages, currently documenting the
     libdistcache APIs;
     - DC_CTX_new.pod (all DC_CTX functions)
     - DC_PLUG_new.pod (DC_PLUG_[new|free|to_select|io] functions)
     - DC_PLUG_read.pod (all other DC_PLUG functions)
     [Geoff Thorpe]

  *) Fix the libdistcache Makefile to not list a header as a source file and
     to also install dc_enc.h as an exported API header.
     [Geoff Thorpe]

  *) Commit an initial version of a ".spec" file for building distcache RPMs.
     [Geoff Thorpe]

  *) Comment out openssl probes and configuration from our autoconf support so
     that (in-progress) work on RPM scripts and what-not do not automatically
     create package dependencies on openssl.
     [Geoff Thorpe]

  *) Flesh out the existing man pages to be (a little) more complete, and add
     more man pages to supplement them. The man pages available are now;
     - distcache(8)
     - dc_server(1)
     - dc_client(1)
     - dc_snoop(1)
     - dc_test(1)
     [Geoff Thorpe]

  *) Make "-connect" and "-server" aliases in dc_snoop for consistency with the
     syntax used by dc_client.
     [Geoff Thorpe]

  *) Started creating 'pod' documentation. This work is incomple
     [Geoff Thorpe]

  *) Pre-empty failure on HPUX by testing for "-ldld" as needed by OpenSSL's
     DSO code.
     [Geoff Thorpe]

Changes between 0.2 and 0.3
---------------------------

  *) Rename "test_session" to "dc_test" to keep with the naming convention
     for all utilities.
     [Geoff Thorpe]

  *) Tidy up the "bootstrap.sh" script and add support for two built-in gcc
     configurations. If the PRECONF environment variable is set, then the
     bootstrap script will automatically invoke "./configure" with preset
     CFLAGS. The two built-in options are PRECONF=[gcc-RELEASE|gcc-DEBUG].
     [Geoff Thorpe]

  *) Add two switches to test_session to allow controlling the size of session
     data when generating sample sessions manually. This doesn't apply in the
     OpenSSL case, but I have disabled the use of OpenSSL in test_session too
     as it wasn't terribly useful and adds complexity to the build system.
     [Geoff Thorpe]

  *) Fix a "flushing" bug in libdistcache that would occasionally not fully
     advance the state-machine of a "plug" in either the read or write
     direction.  This occurred when a connection's read or write buffer
     contained data for more than one fragment of message - sometimes a
     subsequent fragment would not be pulled (or pushed) through, leading to
     occasional hangs in a select() waiting for traffic that has already been
     received. This should finally mark the end of the "works for a while then
     hangs" problems we were seeing.
     [Geoff Thorpe]

  *) Add a helper program, "dc_snoop", to act as a transparent proxy. When a
     client connects, a corresponding peer connection is set up to the
     configured back-end server and data is transparently proxied back and
     forth - meanwhile it is analysed and various information can be displayed
     to the console.
     [Geoff Thorpe]

  *) Correct some comments, and make sure *all* code agrees on a fragmentation
     size of 2048 for messages broken into fragments. This affects binary
     compatibility with 0.2, but 0.2 was (in some cases) broken in this respect
     anyway. In any case, the protocol version is bumped to ensure subsequent
     versions don't try to talk to older versions.
     [Geoff Thorpe]

  *) A variety of changes to libnal
     - get rid of unused (and horrible) NAL_***_move() functions,
     - change a miniscule helper function to a more readable macro,
     - re-organise the helper macros into their own section of code,
     - Consolidate the malloc/free code with the init/finish code as
       malloc/free is the only mechanism declared in the libnal API,
     - improve parameter checking,
     - improve some logic such that a structure's elements are only
       changed if success of the function is guaranteed - makes error-handling
       easier,
     - regard accepted connections as automatically "established" even
       if they are non-blocking.
     [Geoff Thorpe]

  *) Avoid more "statement will never be executed" and signed/unsigned
     warnings. Use "do { ... } while(0)" bracings in the libnal typesafe
     macros.
     [Geoff Thorpe]

  *) Fixed two nasty bugs caused by uninitialised structure elements in
     sessclient. Thanks to valgrind.
     [Geoff Thorpe]

  *) Make some macros in libnal/common.h more robust against semi-colons, or
     expressions being used as parameters. Also, clarify and simplify some
     timeval handling in libnal/sys.c.
     [Geoff Thorpe]

  *) Fixed some "cached_idx" nastiness found in libdistcacheserver where -1,
     which was used to indicate "nothing cached", was not being checked and
     instead populated into an unsigned integer as a valid index. Also fixed
     some weird-looking code found during the bug-hunt.
     [Geoff Thorpe]

  *) Fix the "ISO C89 compiler" warnings about string constants longer than 509
     characters by re-declaring them as arrays of strings. This means the
     utility programs display their usage messages by displaying each string in
     the array separated by newlines.
     [Geoff Thorpe]

  *) Remove unexecutable code, and correct some more signed/unsigned
     mismatches.
     [Geoff Thorpe]

  *) Indent #error directives (so "traditional" C pre-compilers ignore them)
     and unindent any #define directives (so the same pre-compilers don't
     ignore them).
     [Geoff Thorpe]

  *) Some signed/unsigned mismatches were causing integer variables, that use
     -1 as a special case, to be munged and not treated as negative. This was
     causing some array smashing and other weirdness.
     [Geoff Thorpe]

  *) Fixed include paths in automake so that any build directory, different to
     the source-tree itself, can be used by running;
         /path/to/distcache/configure --srcdir=/path/to/distcache ...
     [Joe Orton <jorton@redhat.com>]

  *) If the build system contains pkg-config, use that to establish compiler
     and linker flags for building against OpenSSL.
     [Joe Orton <jorton@redhat.com>]

  *) Re-order some autoconf checks, eg. check library/linkage first so that
     additional linker flags (such as "-lnsl -lsocket" on Solaris) are
     available before we check for specific functions.
     [Steve Robb]

  *) Extend NAL_daemon() for platforms that don't provide the daemon(3)
     function (eg. Solaris) by implementing our own fallback version.
     [John Milton <john.milton@fxfn.com> and Steve Robb]

  *) Upgrade the mod_ssl (apache 1.3.*) support to mod_ssl-2.8.12
     [Steve Robb]

  *) Change the name of the executables "sclient" and "sserver" to "dc_client"
     and "dc_server" to avoid name-clashes with the Kerberos distribution.
     [John Milton <john.milton@fxfn.com> and Geoff Thorpe]

  *) Add a demo client certificate (taken from my "tunala" demo in OpenSSL) for
     use in "test_session" when generating sample sessions containing peer-
     certificates.
     [Geoff Thorpe]

Changes between 0.1-seed and 0.2
--------------------------------

  *) Altered the binary protocol used by distcache to begin each message with a
     32-bit protocol level. The top 16-bit word of this is a "protocol value"
     which must be identical for peers to interoperate (though a server with a
     higher value could respond to the first request by adopting the peer's
     protocol). The lower 16-bit word is a "patch level" which allows the more
     recent of two peers to decide if it should accept communications or not
     with the peer (and work around older bugs if necessary).
     [Geoff Thorpe]

  *) Added DISTCACHE_CLIENT_API and DISTCACHE_CLIENT_BINARY version defines to
     dc_client.h so that apache/mod_ssl plugins can run sanity checks on the
     version of distcache.
     [Geoff Thorpe]

  *) Allow building without OpenSSL support (only affects test_session which
     can generate garbage sessions to test with rather than OpenSSL-compatible
     ones).
     [Geoff Thorpe, Steve Robb]

  *) Add "-pidfile" and "-daemon" switches to the 'sserver' utility.
     [Geoff Thorpe]

  *) Added a self-test script to test sserver and sclient with test_session.
     [Geoff Thorpe]

  *) Removed various things from 0.1-seed that aren't relevant;
     - IN_MAKEDEPEND hacks no longer needed as autoconf/automake handle
       dependencies.
     - wrapper functions removed for unneeded stuff, fork(), waitpid(), etc.
     - NAL_SELECTOR_create() removed too.
     - NAL types are always dynamic now, so init() functions aren't needed to
       initialise static versions.
     - Get rid of some unnecessary types and use just DC_ERR where possible
       (this altered the protocol slightly).
     [Geoff Thorpe]

  *) Use the autoconf-generated config.h to control #includes.
     [Geoff Thorpe]

  *) Add the first part of autoconf/automake/libtool support to distcache
     including numerous followup tweaks.
     [Steve Robb]