Net::Clacks::UpgradeGuide - Notes on upgrading Net::Clacks
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.
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 (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.
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 added the socketchmod option to chmod() the socket file so other users can connect to the socket, too.
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.
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.
The server is implemented in Net::Clacks::Server.
The client library in Net::Clacks::Client.
A more Cache::Memcached compatible client library (caching only, no real time communication) is implemented in the Net::Clacks::ClacksCache module.
Please also take a look at the examples, this implements a simple chat client.
Please refer to the included protocol.txt file for information about the CLACKS protocol.
Rene Schickbauer, <cavac@cpan.org>
The official source code repository is located at: https://cavac.at/public/mercurial/Net-Clacks/
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.
To install Net::Clacks::Server, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Clacks::Server
CPAN shell
perl -MCPAN -e shell install Net::Clacks::Server
For more information on module installation, please visit the detailed CPAN module installation guide.