The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

JSON::RPC2::TwoWay::Connection - Transport-independent bidirectional JSON-RPC 2.0 connection

SYNOPSIS

  $rpc = JSON::RPC2::TwoWay->new();
  $rpc->register('ping', \&handle_ping);

  $con = $rpc->newconnection(
    owner => $owner, 
    write => sub { $stream->write(@_) }
  );
  @err = $con->handle($stream->read);
  die $err[-1] if @err;

DESCRIPTION

JSON::RPC2::TwoWay::Connection is a connection containter for JSON::RPC2::TwoWay.

METHODS

new

$con = JSON::RPC2::TwoWay::Connection->new(option => ...);

Class method that returns a new JSON::RPC2::TwoWay::Connection object. Use newconnection() on a JSON::RPC2::TwoWay object instead.

Valid arguments are:

- debug: print debugging to STDERR, or if coderef is given call that with the debugging line.

(default false)

- owner: 'owner' object of this connection.

When provided this object will be asked for the 'state' of the connection. Otherwise state will always be 0.

- rpc: the JSON::RPC2::TwoWay object to handle incoming method calls

(required)

- write: a coderef called for writing

This coderef will be called for all output: both requests and responses. (required)

call

$con->call('method', { arg => 'foo' }, $cb);

Calls the remote method indicated in the first argument.

The second argument should either be a arrayref or hashref, depending on wether the remote method requires positional of by-name arguments. Pass a empty reference when there are no arguments.

The third argument is a callback: this callback will be called with the results of the called method.

Call throws an error in case of missing arguments, otherwise it returns immediately with no return value.

callraw

$con->callraw({ method => 'method', params => {..} }, $cb);

Enhances the first argument (which should be a hashref) to a full JSON-RPC 2.0 request object and sends the request. This allows for manipulating and extending the actual request.

The third argument is a callback: this callback will be called with the results of the called method.

Callraw throws an error in case of missing arguments, otherwise it returns immediately with no return value.

the result callback

The result callback is called with 1 or 2 arguments. The first argument is a protocol-error-flag, it contains a error message when there was some kind of protocol error like calling a normal method as a notification.

If there are 2 arguments the first one is always false, the second one will contain the results from the remote method, see "REGISTERED CALLBACK CALLING CONVENTION" in "JSON::RPC2::TwoWay. The full response will be passed for access to any extra fields.

notify

$con->notify('notify_me', { baz => 'foo' })

Calls the remote method as a notification, i.e. no response will be expected. Notify throws an error in case of missing arguments, otherwise it returns immediately with no return value.

handle

$con->handle($jsonblob)

Handle the incoming request or response. Requests (if valid) are passed on to the registered callback for that method. Repsonses (if valid) are passed on to the callback provided in the call.

Handle returns 0, 1 or 2 values. If no value is returned there were no errors during processing. If 1 value is returned there was a 'fatal' error, and the value is the error message. If 2 values are returned there was a 'normal' error, the first value is false, the second value is the error message.

In case of an error, handle will call the provided write callback with a appropriate error response to be sent to the other side. The application using the JSON::RPC2::TwoWay::Connection is advised to close the underlying connection in case of fatal errors.

close

$con->close()

Closes the connection. Recommended to be used to avoid memory leaks due to circular references.

owner

Getter-setter to allow the application to connect the JSON::RPC2::TwoWay::Connection to some internal connection concept.

-head2 state

Getter-setter for the connection state. Evaluated by JSON::RPC2::TwoWay when a method was registered with a state option.

SEE ALSO

ACKNOWLEDGEMENT

This software has been developed with support from STRATO. In German: Diese Software wurde mit Unterstützung von STRATO entwickelt.

THANKS

  • 'greencoloured' for multiple PRs

AUTHORS

  • Wieger Opmeer <wiegerop@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016-2022 by Wieger Opmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.