


=encoding UTF-8

=head1 NAME

JSON::Server - JSON-only server

=head1 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 L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/JSON-Server-0.00_01/examples/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.


=head1 VERSION

This documents version 0.00_01 of JSON-Server
corresponding to L<git commit d8f31a5f05392d8254c0079fe3ed6827d8a0b1fc|https://github.com/benkasminbullock/json-server/commit/d8f31a5f05392d8254c0079fe3ed6827d8a0b1fc> released on Fri Jan 15 18:26:31 2021 +0900.

=head1 DESCRIPTION

This sets up an internet socket through which JSON passes.

=head1 METHODS

=head2 new

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

=over

=item 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.

=item handler

Your handler (callback).

    sub handler ($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 L</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.

=item port

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

=back

=head2 serve

    $js->serve ();

Serves JSON on the specified port. Input is JSON, output is
JSON. Non-JSON input results in an error value being returned. What is
or is not valid JSON is decided by L<JSON::Parse/valid_json>.

=head1 DEPENDENCIES

=over

=item L<IO::Socket>

=item L<JSON::Create>

=item L<JSON::Parse>

=back

=head1 SEE ALSO

=over

=item L<JRPC>

=item L<JSON::RPC::Dispatcher>

=item L<JSON::RPC>

=item L<RPC::JSON>

=back



=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 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.



