NAME

Net::IMP::Remote - connect to IMP plugins outside the process

SYNOPSIS

perl imp-relay.pl ... -M Net::IMP::Remote=addr=imp-host:2000 ...

DESCRIPTION

Net::IMP::Remote works as a normal IMP analyzer, but sends all API calls to a server process, which might be on the local or on a different machine. Current implementation feature connection using UNIX domain sockets or TCP sockets.

The RPC functionality is described in Net::IMP::Remote::Protocol. Net::IMP::Remote::Connection implements interactions using the defined RPCs over a flexible wire protocol. The default wire implementation using the Storable library is done in Net::IMP::Remote::Storable. There is an alternative implementation with the Sereal library in Net::IMP::Remote::Sereal. Net::IMP::Remote::Client and Net::IMP::Remote::Server implement the client and server side of the connection, while Net::IMP::Remote finally implements the usual IMP interface, so that this plugin can be used whereever other IMP plugins can be used, although it's used best in data providers offering an integration into their event loop.

Arguments

This proxy IMP analyzer features the following arguments

addr ip:port|/path

This describes the address, where the IMP server can be reached. This can be an absolute path (UNIX domain socket) or ip:port. IPv6 is supported if IO::Socket::IP or IO::Socket::INET6 are available.

fail 'hard'|'soft'

This defines the behavior in case the connection to the IMP server fails when creating a new analyzer object for a connection. On the default 'hard' a failed connection will result in an analyzer returning only IMP_FATAL, thus blocking all data. In case of 'soft' the analyzer will return an error log message but then issue an IMP_PASS for both directions, so that data pass unchanged.

If the connections to the IMP server breaks while analysis is already taking process it will currently fail hard.

Implementation and Overhead

Unlike other solutions like ICAP, IMP tries to keep the overhead small. A new connection to the IMP RPC server is done once, when the factory object is created. Traffic for all analyzers created from the factory will be multiplexed over the same connection, thus eliminating costly connection setup. All RPC calls, except the initial get_interface after creating the factory object, are asynchronous, because they don't need an immediate reply to continue operation.

Integration Into Data Providers Event Loop

While it is possible to use Net::IMP::Remote without an event loop it is slower, because all read and write operation will block until they are done. But the data provider might provide a simple event loop object within the new_factory call:

my $factory = Net::IMP::Remote->new_factory(
  addr => 'host:port',
  eventlib => myEventLib->new
);

The event lib object should implement the following simple interface

ev->onread(fh,callback)

If callback is given it will set it up as a read handler, e.g. whenever the file handle gets readable the callback will be called without arguments. If callback is not given it will remove any existing callback, thus ignoring if the file handle gets readable.

ev->onwrite(fh,callback)

Similar to onread, but for write events

ev->timer(after,callback,[interval]) -> timer_obj

This will setup a timer, which will be called after after seconds and call callback. If interval is set it will reschedule the timer again and again to be called every interval seconds. Ths method returns an object timer_obj. If this object gets destroyed the timer will be canceled.

TODO

See TODO file in distribution

SEE ALSO

Storable Sereal::Encoder Sereal::Decoder

AUTHOR

Steffen Ullrich