NAME
Protocol::OVSDB - Implementation of RFC 7047 (Open vSwitch Database Management protocol)
SYNOPSIS
use Protocol::OVSDB;
use IO::Socket::IP;
my $sock = IO::Socket::IP->new( '127.0.0.1:6640' );
my $ovsdb = Protocol::OVSDB->new(
on_send => sub { syswrite( $sock, $_[0] ); },
on_result_response => sub { say 'Yay!' },
on_error_response => sub { say 'Nope...' }
);
$sock->connect;
$ovsdb->list_dbs( sub { say $_ for $_[0]->@* } );
sysread( $sock, my $buf, 10240 );
$ovsdb->receive( $buf );DESCRIPTION
This module implements the Open vSwitch (OVS) Database Management protocol. It can be used to query OVS or OVN databases, or listen for updates. New databases can be developed using the OVSDB database engine. The module provides all methods required to insert and modify data in such databases.
In line with other modules in the Protocol::* namespace, this module does not handle the actual connection. Requests to send data are handled through the on_send callback.
NOTE The OVS project encourages the use of their CLI tools to update data in the database, because those tools ensure validity of the database. Those validations are not in the server. Updates coming from this module won't be validated.
CONSTRUCTORS
new
$ovsdb = Protocol::OVSDB->new( %params );Creates a new OVSDB protocol handler instance with %params. Recognized parameters are:
on_send(required)sub on_send( $data ) { ... }A callback triggered when data is to be sent.
on_notificationsub on_notification( $method, $params ) { ... }A callback triggrered when a notification is received.
on_requestsub on_request( $method, $params, $id ) { ... }A callback triggered when a request is received. This only applies when the instance is used as a server; clients won't see this callback being triggered.
INPUT METHODS
receive
$ovsdb->receive( $data );Receives data from a connection and decodes it into protocol messages.
BASIC PROTOCOL METHODS
send_notification
$ovsdb->send_notification( $method, $params );Sends a notification to the connected party. Notifications typically name the methods stolen, locked or update.
send_request
my $id = $ovsdb->send_request( $method, $params, $cb );Sends a request to the server, returning the $id. This $id can later be used to cancel outstanding requests, where applicable.
send_result
$ovsdb->send_result( $result, $id );Either this method or send_error should be used to respond to a received request. This method sends a message indicating succesfull completion of the request.
send_error
$ovsdb->send_error( $error, $id );Either this method or send_result should be used to respond to a received request. This method sends a message indicating failed completion of the request.
FUNCTIONAL RPC METHODS
list_dbs
$ovsdb->list_dbs( sub($dbs, $error) { ... } );Sends a request to the server to list available databases in the connected database engine. Either $dbs or $error is defined.
get_schema
$ovsdb->get_schema( $db, sub($schema, $error) { ... } );Sends a request to the server to list the database schema for the given database. Either $schema or $error is defined.
transact
my $transact_id = $ovsdb->transact( $db, $ops, $cb );Sends a request to the server to execute a series of operations.
cancel
$ovsdb->cancel( $transact_id );This sends a notification to the server that the currently running transact call needs to be cancelled.
monitor
$ovsdb->monitor( $db, $monitor, $monitor_requests, sub($monitor, $error) { ... } );Sends a set of monitoring requests to the server. $monitor must be an instance of Protocol::OVSDB::Monitor. The callback is called with the result of the RPC request. Either $monitor or $error is defined.
The initial update notification is the entire table content matching the update queries, when the monitoring request requires one.
Monitoring started by this function can be stopped using the cancel method in the monitor:
$monitor->cancel( $cb );lock
$ovsdb->lock( $lock, sub($result, $error) { ... } );The $lock is an instance of Protocol::OVSDB::Lock. Note that locks are server-wide, not restricted to a specific database.
If the lock could be acquired immediately, $result contains a $locked key with a true value. If the lock has not been acquired (it's pending), $result contains a locked key with a false value. A locked notification is issued when the lock is finally acquired.
A lock acquired through this method can be released using $lock-unlock>.
steal
$ovsdb->steal( $lock, sub($result, $error) { ... } );Instructs the server to assign this client the given lock, even if owned by another client.
The current owner of the lock is sent a stolen notification.
echo
$ovsdb->echo( sub { ... } );Checks if the connection is still active.
INTERNAL METHODS
remove_monitor
$ovsdb->remove_monitor( $monitor_id );remove_lock
AUTHOR
Erik Huelsmann
<ehuels@gmail.com>
SEE ALSO
LICENSE AND COPYRIGHT
See the LICENSE file in this distribution.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.