POE::C...JSONRPC(3pm)

💖 POE::Component::Server::JSONRPC — the manual, but make it cute 💖

okay bestie, welcome to POE::Component::Server::JSONRPC (yes that's the whole name, it's giving long but we move). It's a POE component for a tcp or http based JSON-RPC server. Sit down, grab a strawberry, let's go ✨

---

🌸 SYNOPSIS 🌸

#http version:
POE::Component::Server::JSONRPC::Http->new(
    # consider using something like JSON::MaybeXS for better performance
    json    => JSON::MaybeXS->new->utf8->allow_nonref,
    Port    => 3000,
    Handler => {
        'echo' => 'echo',
        'sum'  => 'sum',
    },
    SslKey  => '/path/to/the/server.key',
    SslCert => '/path/to/the/server.crt',
    Authenticate => \&authentication_handler,
    # authentication_handler must be a function that takes two parameters login and password,
    # and returns true if connection is successful, false otherwise
);

#tcp version:
POE::Component::Server::JSONRPC::Tcp->new(
    Port    => 3000,
    Handler => {
        'echo' => 'echo',
        'sum'  => 'sum',
    },
);

sub echo {
    my ($kernel, $jsonrpc, $id, @params) = @_[KERNEL, ARG0..$#_ ];

    $kernel->post( $jsonrpc => 'result' => $id, @params );
}

sub sum {
    my ($kernel, $jsonrpc, $id, @params) = @_[KERNEL, ARG0..$#_ ];

    $kernel->post( $jsonrpc => 'result' => $id, $params[0] + $params[1] );
}

like, look at that. it's a whole little server in a code block. we love to see it 🫶

---

✨ DESCRIPTION ✨

This module is a POE component for tcp or http based JSON-RPC Server. no cap.

The spec is defined over at http://json-rpc.org/, and this module uses the JSON-RPC 1.0 spec. Quick tea: 1.1 does not cover tcp streams, so that's why we're on 1.0. periodt 💅

---

👑 METHODS 👑

🌈 new

Creates the JSONRPC component session and hands you back the session id. iconic behaviour honestly.

Parameters:

• Port — the port number for listen. that's it, that's the vibe 🎀
• Handler — a hash variable where the key is the handler name and the value is the handler's poe state name.
  • The handler name (the key) is used as the JSON-RPC method name.
  • So if you send {"method":"echo"}, this module calls the poe state named "echo". fr fr, that's the whole trick 💀

---

💜 HANDLER PARAMETERS 💜

• ARG0 — a session id of PoCo::Server::JSONRPC itself.
• ARG1 — the id of the client you're treating, send that back in result/error.
• ARG2 .. ARGN — the JSONRPC argguments ✨

ex) If you send following request

{"method":"echo", "params":["foo", "bar"]}

then the "echo" handler is called and the parameters are: ARG0 is the component session id, ARG1 is the client id, ARG2 is "foo", ARG3 is "bar". told you it was clean 🌸

---

🎀 HANDLER RESPONSE 🎀

You must call either the "result" or the "error" state inside your handlers to respond with a result or an error. no skipping, bestie, the client is waiting 😭

ex:

$kernel->post( $component_session_id => "result" => $client_id, "result value" )

$component_session_id is ARG0 in the handler. If you do the above, the response is:

{"result":"result value", "error":""}

slay. look at that lil response go 🦋

---

⭐ POE METHODS ⭐

Inner method for POE states. iykyk.

poe__start

poe_init_server

Should be defined in Http or Tcp 👑

poe_input_handler

poe_result

poe_error

poe_send

Should be defined in Http or Tcp 👑

---

Côme Chilliet <mcmic@cpan.org> and Daisuke Murase <typester@cpan.org> — the actual legends behind this, respect 💖

💅 COPYRIGHT 💅

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

The full text of the license can be found in the LICENSE file included with this module.

---

okay that's the whole page, you're officially certified on POE::Component::Server::JSONRPC, go build something cute with it 🌈

this was perl v5.28.1, dated 2019-01-06, from the POE::C...JSONRPC(3pm) manual page — mwah, love u, bye bestie 🫶💖✨