=head1 NAME

Net::Clacks::UpgradeGuide - Notes on upgrading L<Net::Clacks>

=head1 SYNOPSIS

This document lists important information when upgrading from previous versions of L<Net::Clacks>.

Please be sure to read all relevant sections of this short guide. While i myself don't like breaking/incompatible
changes, bugfixes and major enhancements sometimes make them the most painless way of handling things.

On the bright side, after you've gone through this document and implemented required changes (if any), you get
to enjoy a newer, shinier version of your favourite real time interprocess messaging system. While i strive to
remove bugs in each release, sometimes new ones creep in. Just keep bugging me about them until i fix them as well.

=head1 IMPORTANT UPGRADE NOTES

=head2 VERSION 6

Version 6 (and higher) of L<Net::Clacks::Server> imlements a smarter interclacks sync. Make
sure to upgrade all nodes on your local clacks network at the same time! While the protocol itself
is mostly backward compatible, interclacks sync will fail otherwise.

Version 6 also includes a smarter shutdown sequence for L<Net::Clacks::Client> and the ability to 
persistantly store the clackscache data in a file in L<Net::Clacks::Server>. The file format has also
changed somewhat from previous beta versions of this feature due to the implementation of smarter 
sync. If you have used persistance before, you might (or might not) have to reset/remove the persistance
file.

This change to "smarter" syncing has increased stability of some of my systems using "Net::Clacks", but
has been in use for only a limited time. You should test with your own software before upgrading.

=head2 VERSION 7

Version 7 (and higher) of L<Net::Clacks::Server> and L<Net::Clacks::Client> implement a lot of
bugfixes and improvements. This includes authentication timeouts, somewhat smarter automatic reconnects
and stuff like that.

While the protocol in theory is backwards compatible to version 6, it is strongly recommended that you
upgrade ALL nodes (clients and servers) in your network at the same time. I have done only limited testing
with backward compatibility and i would not recommending a mix&match approach on critical systems.

=head2 VERSION 8

On Systems that support Unix domain sockets and have IO::Socket::UNIX installed,
L<Net::Clacks::Server> and L<Net::Clacks::Client> can now use Unix domain sockets
for local communication. See the examples for. This might or might not drastically
lower CPU usage, depending on your hardware, software, weather on moon phase.

Version 8 also includes a number of bugfixes and improvements. This includes a better
way of detecting closed/broken connection which should prevent servers and clients
from holding on to closed connection until it times out. This should also lower CPU
usage under certain circumstances. This is far from perfect, though and may lead to
some false positives (e.g. accidental closure of perfectly fine connections) thanks
to the combination of SSL and non-blocking sockets.

Version 8 is fully backwards compatible with Version 7 on the network layer (no protocol change),
but as always it is recommended to update all servers and clients at the same time if possible.

One important client API change (sort of) is the generation of messages with type "reconnected"
after a connection has been re-established. After receiving this message, a client application
must resend any LISTEN calls it wants to make. While in previous versions, this was accomplished
by checking for type "disconnect" messages, this was unreliable at best. The "reconnected" message
is generated internally B<after> a new connection has been established, except on the first ever
connection. Technically, at that point in time L<Net::Clacks::Client> has spooled the Auth request
to the server, but may not have recieved the answer yet, but i'll assume here that you have configured
your client correctly.

=head2 VERSION 9

Version 9 added the socketchmod option to chmod() the socket file so other users can connect to the socket, too.

=head2 VERSION 10

WARNING: BREAKING CHANGES! It is required to update all servers and clients at the same time.

Version 10 disables SSL on Unix Domain Sockets for better local performance. This version also adds the
ability to run interclacks through Unix Domain Sockets, in case you want to run a master/slave setup locally. This
should not really affect security, though. If an attacker has enough permissions to spy on a Unix Domain Socket,
they will most likely also have the ability to gain access to the configuration files and SSL keys of the Clacks server
running on the same host..

This version also has a slightly improved timeout handling when a slave reconnects to the master at the cost
of a bit more traffic during the initial setup phase.

In the protocol, error messages have been implemented via the "E" flag in the "OVERHEAD" command. L<Net::Clacks::Client>
forwards this to the client software via a clacks message of type "error_message".

In theory, the only *breaking* incompatible change is contained in handling Unix Domain Sockets. You could (try to) upgrade
to Version 10 client-by-client if you don't use Unix Domain Sockets, but this is neither tested nor recommended.

=head2 VERSION 11

Under certain circumstances L<Net::Clacks::Client> would hang or otherwise error out during DESTROY(). This is due to
the fact that the underlying socket might already have been DESTROYed by perl. I could reliably produce hangs in 
certain applications when calling exit(0) in the main loop.

In Version 11, the DESTROY method now uses eval() to try and catch any errors. It is recommended that you use the new
disconnect() function in L<Net::Clacks::Client> BEFORE exiting the program or deleting the last reference to the instance.
This will then try to send out any remaining commands in the output buffer. Simply exiting the program will still work,
but there is a good chance that anything still remaining in the output buffer after your last call to doNetwork() will
NOT be sent.

Version 11 also implements a Unicode/UTF8 bugfix. This should have no visible side effects in pretty much all use-cases of
L<Net::Clacks>

Upgrading to version 11 on a client-by-client basis should work fine since there have been no incompatible changes,
but this has only seen limited testing. As always, it is recommended to upgrade everything in one go.


=head1 MODULES

The server is implemented in L<Net::Clacks::Server>.

The client library in L<Net::Clacks::Client>.

A more Cache::Memcached compatible client library (caching only, no real time communication) is implemented
in the L<Net::Clacks::ClacksCache> module.

Please also take a look at the examples, this implements a simple chat client.

=head1 IMPORTANT NOTE

Please refer to the included protocol.txt file for information
about the CLACKS protocol.

=head1 AUTHOR

Rene Schickbauer, E<lt>cavac@cpan.orgE<gt>

=head1 Source code repository

The official source code repository is located at:
L<https://cavac.at/public/mercurial/Net-Clacks/>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2008-2020 Rene Schickbauer

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.0 or,
at your option, any later version of Perl 5 you may have available.

=cut

