server: add the ability to have > 1 stages of trickle handling

[davidpanderson]

Some projects (namely CPDN) need to process trickle-up messages
with two different daemons.
We do this as follows:

• daemon 1 enumerates messages with handled==0, and sets handled=1
• daemon 2 enumerates messages with handled==1, and sets handled=2
  You can then purge records with handled==2

To implement this, trickle_handler.cpp has two global vars,
int handled_enum and int handled_set.
By default these are 0 and 1.
For daemon 2, set them to 1 and 2 in trickle_handler_init()

[ChristianBeer]

While at it, why not fix the problem with rogue xml in the trickle message? See: #1485

[ChristianBeer]

Code looks good. I'll do a final test soon and then merge.

[ChristianBeer]

We should add a comment in code and in documentation that the purge_trickles.php script needs to be changed when using multiple stages.
I personally also find it more useful to use -1 as an error indicator by default. That makes it easier to look for problematic content.

[davidpanderson]

Done

[ChristianBeer]

Is the actual usage message missing? The single word usage seems not very descriptive. We have to keep in mind that not all projects read the source code of the ops scripts.

[ChristianBeer]

A short update on review progress. I want to add some automated tests for this part of the code to the server integration testing which is almost ready. Once the minor documentation issue in purge_trickles.php is fixed I'm going to merge.

[TheAspens]

@ChristianBeer - is the only delay on merging this your note about?

We should add a comment in code and in documentation that the purge_trickles.php script needs to be changed when using multiple stages.

[davidpanderson]

Actually you don't need to change the script; see
https://boinc.berkeley.edu/trac/wiki/TrickleApi#Purgingtricklemessages

[ChristianBeer]

The documentation is fine. What I meant is the error message in purge_trickles.php that is shown when the wrong number of parameters is used. It currently just says "usage" and the user needs to take a look at the code to get the proper information. Since the usage is rather simple the error message should contain what is basically the comment at the top of the file.

// no args: delete both up and down messages with handled != 0
// msg_from_host N
//    delete trickle ups with handled==N
// msg_to_host N
//    same, trickle down

This is what you expect from other programs too.

[TheAspens]

@davidpanderson - I think the only thing holding up @ChristianBeer from merging this pull request is his comment above. If you could review his comment and respond I think Christian will be able to merge.

Thanks - I just wanted to nudge this one along so that we can merge it.

[davidpanderson]

This is a one-off for CPDN; fine as is.

[TheAspens]

@davidpanderson - This looks like a useful ops function that we might use as well (we use trickle messages on one of our applications). I suspect that it will be used on more projects than just CPDN. Could you change the usage section from what you have now:

} else {
    echo "usage\n";
}

to

} else {
    echo "usage: purge_trickles.php [msg_from_host | msg_to_host]\n";
}

and then I think this will be ready for merge. Thanks!

[AenBleidd]

@davidpanderson, could you please make the fixes @TheAspens asked for? Thanks