The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Net::Clacks::UpgradeGuide - Notes on upgrading Net::Clacks

SYNOPSIS

This document lists important information when upgrading from previous versions of 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.

IMPORTANT UPGRADE NOTES

VERSION 6

Version 6 (and higher) of 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 Net::Clacks::Client and the ability to persistantly store the clackscache data in a file in 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.

VERSION 7

Version 7 (and higher) of Net::Clacks::Server and 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.

VERSION 8

On Systems that support Unix domain sockets and have IO::Socket::UNIX installed, Net::Clacks::Server and 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 after a new connection has been established, except on the first ever connection. Technically, at that point in time 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.

VERSION 9

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

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. 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.

VERSION 11

Under certain circumstances 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 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 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.

VERSION 12

This is mostly an internal bugfix release. It now again allows in install Net::Clacks directly, instead of requiring the user to name the full sub-module name ("Net::Clacks::Client").

In this release, a new disconnect() method was added to Net::Clacks::ClacksCache. This will allow to disconnect cleanly from the server.

VERSION 13

Before this version, Net::Clacks::Server will always cache deleted keys for one week. Caching is needed for clean reconnection of interclacks links.

But the long caching time can lead to all sorts of problems, especially with things like cached web sessions or temporary cookies, that sort of thing. Cache time of deleted keys is really a trade off between the ability of interclacks links to sync cleanly after long interruptions of the connection and the memory and bandwidth required to do so.

Version 13 now defaults to 1 hour (3600 seconds) of caching deleted keys. This can be changed in the "deletedcachetime" config setting.

Syncing now also better handles timeout situations during long sync by avoiding them. Well, i hope it does. Fingers crossed, really...

This release is backwards compatible with Version 12. But it is highly recommended to upgrade at least all server nodes to this version as soon as possible to avoid all sorts of problems.

VERSION 14

Version 14 has only internal bugfixes and no externally incompatible changes.

The main "feature" of this release is more internal error checking. This is to detect broken connections sooner and a bit more reliable.

VERSION 15

Version 15 adds the configuration variable "persistanceinterval" (defaults to 10 seconds for backward compatibility). This defined the interval in which a persistance file is written. You could lower it for more frequent checkpointing, but more importantly you could increase to longer time spans to reduce disk activity.

VERSION 16

Version 16 Server now croaks with a descriptive message if it encounters an invalid persistance file.

This version does not introduce any incompatible changes.

AUTHOR

Rene Schickbauer, <cavac@cpan.org>

Source code repository

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

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.