/ 
Protocol-Dqlite-0.02
River stage zero No dependents
/ Protocol::Dqlite

NAME

Protocol::Dqlite - Dqlite in Perl

SYNOPSIS

use autodie;

my $dqlite = Protocol::Dqlite->new();

my $socket = IO::Socket::INET->new('127.0.0.1:9001') or die;

syswrite $s, Protocol::Dqlite::handshake();

# Register ourselves as a Dqlite client:
syswrite $s, Protocol::Dqlite::request( Protocol::Dqlite::REQUEST_CLIENT, 0 );

# Await the server’s acknowledgement:
while (sysread $s, my $buf, 512) {
    my ($msg) = $dqlite->feed($buf);
    next if !$msg;

    last if $msg isa Protocol::Dqlite::Response::WELCOME;

    # An unexpected response. Better bail out …
    #
    require Data::Dumper;
    die Data::Dumper::Dumper($msg);
}

… and now you can exchange messages as you wish.

DESCRIPTION

This module implements message parsing and creation for Dqlite clients. To use this module you’ll need to write the I/O logic yourself.

CHARACTER ENCODING

Strings designated as “blob”s are byte strings.

All other strings into & out of this module are character strings.

Decode & encode accordingly.

CONSTANTS

The following derive from the documentation of Dqlite’s wire protocol as well as protocol.h in Dqlite’s source code.

Role Codes

ROLE_VOTER, ROLE_STANDBY, ROLE_SPARE

Tuple Member Types

  • Numbers: TUPLE_INT64, TUPLE_FLOAT

  • Buffers: TUPLE_STRING, TUPLE_BLOB

  • Time: TUPLE_UNIXTIME, TUPLE_ISO8601

  • Other: TUPLE_NULL, TUPLE_BOOLEAN

Request Message Types

  • REQUEST_LEADER (0)

  • REQUEST_CLIENT (1)

  • REQUEST_OPEN (3)

  • REQUEST_PREPARE (4)

  • REQUEST_EXEC (5)

  • REQUEST_QUERY (6)

  • REQUEST_FINALIZE (7)

  • REQUEST_EXEC_SQL (8)

  • REQUEST_QUERY_SQL (9)

  • REQUEST_INTERRUPT (10)

  • REQUEST_CONNECT (11)

  • REQUEST_ADD (12)

  • REQUEST_ASSIGN (13)

  • REQUEST_REMOVE (14)

  • REQUEST_DUMP (15)

  • REQUEST_CLUSTER (16)

Other

  • handshake - The string to send after establishing a connection to the server.

STATIC FUNCTIONS

$bytes = request( $TYPE, @ARGUMENTS )

Returns a byte buffer of a Dqlite message. $TYPE is one of the REQUEST_* constants listed above.

@ARGUMENTS are as Dqlite’s wire protocol documentation indicates. Dqlite tuples are expressed as type/value pairs.

Example:

my $bytes = Protocol::Dqlite::request(
    Protocol::Dqlite::REQUEST_PREPARE,
    12,
    "SELECT ?, ?",
    Protocol::Dqlite::TUPLE_INT64 => 12345,
    Protocol::Dqlite::TUPLE_BLOB => "\x00\x01\x02",
);

METHODS

$obj = CLASS->new()

Instantiates CLASS.

@messages = OBJ->feed( $BYTES )

Give new input to OBJ. Returns any messages parsed out of $BYTES as Protocol::Dqlite::Response instances.

RESPONSE CLASSES

All of the below extend Protocol::Dqlite::Response. They expose various accessors as documented below:

  • Protocol::Dqlite::Response::FAILURE: code(), message()

  • Protocol::Dqlite::Response::SERVER: id(), address(), role()

  • Protocol::Dqlite::Response::WELCOME: (none)

  • Protocol::Dqlite::Response::SERVERS: count(), id(), address(), role(); the latter 3 require an index argument, which MUST be between 0 and (count() - 1), inclusive.

  • Protocol::Dqlite::Response::DB: id()

  • Protocol::Dqlite::Response::STMT: database_id(), statement_id(), params_count()

  • Protocol::Dqlite::Response::RESULT: last_row_id(), rows_count()

  • Protocol::Dqlite::Response::ROWS:

    • is_final()

    • column_names() - returns a list, or a count in scalar context

    • rows_count()

    • row_types(), row_data() - these need an index, max=(rows_count()-1)

  • Protocol::Dqlite::Response::EMPTY: (none)

  • Protocol::Dqlite::Response::FILES: names() (list/count) and content() (takes an index)