UR::Se...Server(3pm)

💖 UR::Service::JsonRpcServer 💖

okay bestie, so this page is UR::Service::JsonRpcServer(3pm) — a User Contributed Perl Documentation situation — and it's literally a whole JSON-RPC server that lives inside your UR namespaces. self-contained. no outside drama. ✨

---

🌸 NAME 🌸

UR::Service::JsonRpcServer — a self-contained JSON-RPC server for UR namespaces. it's giving "I contain multitudes and also all my own dependencies." 💅

---

🎀 SYNOPSIS 🎀

use lib '/path/to/your/moduletree';
use YourNamespace;

my $rpc = UR::Service::JsonRpcServer->create(host => 'localhost',
                                             port => '8080',
                                             api_root => 'URapi',
                                             docroot => '/html/pages/path',
                                           );
$rpc->process();

look at her. four params and a dream. 🦋

---

✨ Description ✨

so this is a class, and inside this class is an implementation of a JSON-RPC server that answers requests about UR-based namespaces and their objects. the web server back-end? that's Net::HTTPServer. she's standing on shoulders, no cap.

incoming requests get sorted into two major categories, and yes we're listing them because both matter:

• http://server:port/"api-root"/class/Namespace/Class — this is the URL you hit when you want a class method call on Namespace::Class
• http://server:port/"api-root"/obj/Namespace/Class/id — this is the URL you hit for a method call on an object of class Namespace::Class with the given id

two paths, one server, main character energy. 🔥

---

💜 Constructor 💜

the constructor is a named-parameters girlie. here's what she takes:

• host — the hostname to listen on. can be an ip address, a host name, or undef. default is '0.0.0.0'. this argument gets passed along verbatim to the Net::HTTPServer constructor. no edits, no filter, she's going as-is. 💫
• port — the TCP port to listen on. default is 8080. also passed along verbatim to the Net::HTTPServer constructor. periodt.
• api_root — the root path that the http server will listen for requests on. the constructor registers two paths with the Net::HTTPServer using RegisterRegex() — one for /"api_root"/class/* and one for /"api_root"/obj/* — so it can respond to class calls and instance method calls. that's the whole point of her existence fr fr.

and any other arguments? they all get passed along to the Net::HTTPServer constructor. she shares. she's generous. 🫶

---

🌈 Methods 🌈

• $rpc->process() — this is a lil wrapper around the Net::HTTPServer Process() method. with no arguments, this call blocks forever from the caller's perspective, and processes every http request that comes in. iconic, honestly. but you can optionally pass in a timeout value in seconds, and then it'll respond to requests for exactly that many seconds before returning. your call, bestie. 💖

---

🦋 Client Side 🦋

there are (or will be) client-side code in both Perl and Javascript. like, both. versatility.

• the Perl code is (will be) implemented as a UR::Context layer that returns light-weight object instances containing only class info and IDs. all method calls get serialized and sent over the wire for the server process to execute them. it's remote work but make it objects.
• the Javascript interface is defined in the file urinterface.js. example time:

var UR = new URInterface('http://localhost:8080/URApi/');  // Connect to the server
var FooThingy = UR.get_class('Foo::Thingy');  // Get the class object for Foo::Thingy
var thingy = FooThingy.get(1234);  // Retrieve an instance with ID 1234
var result = thingy.call('method_name', 1, 2, 3);  // Call $thingy->method_name(1,2,3) on the server

okay but the comments in that snippet are doing the most and we love that for them. 👑

---

⭐ SEE ALSO ⭐

• Ney::HTTPServer
• urinterface.js

(that first one is spelled exactly how the page spells it, don't come for me 🙈)

---

lowkey reminder bestie: $rpc->process() with no args does not come back. she blocks. forever. if you need her to leave, hand her a timeout in seconds. 🫡

---

and that's the whole page, bestie! this one's from perl v5.32.1, dated 2022-01-17, contributed by the lovely perl documentation girlies — mwah, slay, go build a JSON-RPC server, you got this 💅💖✨🎀