/ 
JSON-Server-0.00_06
River stage zero No dependents
/ JSON::Server

NAME

JSON::Server - JSON-only server

SYNOPSIS

use JSON::Server;
my $js = JSON::Server->new (handler => \& hello, port => '7777', data => 'OK');
$js->serve ();

sub hello
{
    my ($data, $input) = @_;
    return {%$input, hello => 'world', data => $data};
}

(This example is included as synopsis.pl in the distribution.)

Then test your server:

$ perl examples/synopsis.pl &
$ telnet localhost 7777
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"I'm feeling lucky":"punk"}
{
        "I'm feeling lucky":"punk",
        "data":"OK",
        "hello":"world"
}
Connection closed by foreign host.

VERSION

This documents version 0.00_06 of JSON-Server corresponding to git commit 5e713caec4e39c91e0ea443a4a3376095cb63519 released on Mon Feb 8 00:25:52 2021 +0900.

DESCRIPTION

This sets up an internet socket through which JSON passes.

METHODS

new

    my $js = JSON::Server->new (handler => \& something, data => $my_data,
		                port => '3737');
data

Your data which you want to pass to the handler. This can be omitted, in which case the handler will be sent an undefined value as its first argument.

handler

Your handler (callback).

sub handler
{
    my ($data, $input) = @_;
    return {error => "I don't like this input"};
}
my $js = JSON::Server->new (handler => \&handler);

The handler function should accept two arguments, the first is the user data which is supplied to "new" and the second is the parsed input from the socket. It should return one value which is then passed back through the socket as JSON. The user handler function does not serialize or deserialize anything, usually it would take a hash reference as an argument and return a hash reference as result.

If you do not supply a handler, the server substitutes an echo function which merely returns your input back to you, and prints a warning.

port

The port to serve on. This needs to be specified, there is no default value.

serve

$js->serve ();

Serves JSON on the specified port. Input is JSON, output is JSON. Non-JSON input results in a response of the form {"error":"invalid JSON"} being returned. What is or is not valid JSON is decided by "valid_json" in JSON::Parse.

JSON

Booleans

Unlike many programming languages, Perl doesn't have true and false, which means that boolean literals (true and false) can become something of an issue when using JSON. In JSON::Create there are all kinds of options for using booleans, but JSON::Server doesn't give access to the underlying module.

However, as a way to get booleans, if you need them, JSON::Server uses the CPAN module "boolean". If you need true or false in your JSON output, add

use boolean;

in your code and then

my $value = true;

etc. to get true and false literals in the JSON.

Perl's built-in undef will produce JSON null.

Boolean support is planned for a future version of JSON::Parse, and the use of the "boolean" module will no longer be necessary.

Unicode

Perl doesn't allow character-encoded strings through sockets, so character input is automatically downgraded on output using "downgrade_utf8" in JSON::Create, and since JSON is a UTF-8 only format, all input is upgraded to character input. "JSON::Parse" currently doesn't have the facility to do this, so "Unicode::UTF8" is used for that task.

Optional character-string upgrading is planned for a future version of JSON::Parse, and use of the Unicode::UTF8 module will no longer be necessary.

CONTROLLING THE SERVER

There is a "backdoor" for controlling the server. To access this, you need to send an object (a hash reference) with the key JSON::Server::control,

send_to_server ({'JSON::Server::control' => 'stop'});

It accepts the following commands:

stop

{"JSON::Server::control":"stop"} causes the server to return from its event loop. It prints a response {"JSON::Server::response":"stopping"} to acknowledge the control message.

Whatever else is sent in the object with the control message is discarded.

DEPENDENCIES

boolean

boolean is used as the compatibility module for putting true or false values into the JSON.

IO::Socket

This is used to communicate the information to and from the client.

JSON::Create

This is used to encode the response JSON from a native structure.

JSON::Parse

This is used to decode the received JSON into a native structure.

Unicode::UTF8

"decode_utf8" in Unicode::UTF8 is used to convert the received JSON from the socket before it is passed to "JSON::Parse".

SEE ALSO

JRPC
JSON::RPC::Dispatcher
JSON::RPC
RPC::JSON

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2021 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.