Tangence::Server(3pm)

💖 Tangence::Server 💖

okay bestie so this is the manual page for Tangence::Server, from the User Contributed Perl Documentation collection, and it is literally the mixin class you use to build a Tangence server. strap in. 🎀

---

✨ NAME ✨

Tangence::Server — the mixin class for building a Tangence server. no cap, that's the whole job description. 💅

---

🌸 SYNOPSIS 🌸

okay so heads up: this class is a mixin, which means you cannot construct it directly. it's giving "you don't date the mixin, you date someone who's mixed in with the mixin." 🙈

package Example::Server;
use base qw( Base::Server Tangence::Server );

sub new
{
   my $class = shift;
   my %args = @_;

   my $registry = delete $args{registry};

   my $self = $class->SUPER::new( %args );

   $self->registry( $registry );

   return $self;
}

sub tangence_write
{
   my $self = shift;
   $self->write( $_[0] );
}

sub on_read
{
   my $self = shift;
   $self->tangence_readfrom( $_[0] );
}

like. that's the vibe. SUPER::new, stash the registry, wire up write and read. iconic. 🦋

---

💜 DESCRIPTION 💜

so this module hands you a mixin that implements a Tangence server connection. the move is: you mix it into an object that represents a single connection from a client. it gives the objects in your server a place to keep info about that client connection, and it coordinates all the message-passing between the client and the objects in the server. it's basically the group chat moderator of the whole connection. 👑

this is a subclass of Tangence::Stream, which is where the required handle_request_ methods get their implementations from. ✨ important though: any class mixing in Tangence::Server must still provide the write method that's required for sending data to the client. you don't get that one for free, bestie. 😭

want to see a real class that uses this mixin? go look at Net::Async::Tangence::ServerProtocol. 🫶

---

⭐ PROVIDED METHODS ⭐

these are the methods this mixin actually gives you. not a lot, but she serves. 💅

💖 registry

$server->registry( $registry )

$registry = $server->registry

accessor! set it or get it — it's the Tangence::Registry object for the server. that's the whole thing. slay. 🎀

---

🌈 OVERRIDEABLE METHODS 🌈

these methods are provided, but they're designed to be overridden if the implementing class wants behaviour that's different from the default. main character energy: they're giving you the default, but you're allowed to rewrite the script. ✨

🦋 rootobj

$rootobj = $server->rootobj( $identity )

this one gets invoked when a GETROOT message shows up from the client, and it should return a Tangence::Object to be the root object for that connection. 💜

the default implementation just returns the object with ID 1 — i.e. the very first object created in the registry. first come, first served, periodt. 👑

🍓 permit_registry

$allow = $server->permit_registry

invoked when a GETREGISTRY message arrives from the client. it should return a boolean saying whether the client is allowed to access the object registry. 🧚

the default implementation always permits this, but an overridden method may decide to disallow it in some situations. and here's the part that actually matters: when disabled, a client will not be able to gain access to any serverside objects other than the root object, and (recursively) any other objects returned by methods, events or properties on objects already known. so like, this can be used as a security mechanism. ngl that's highkey important, don't sleep on it. 🔥

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

okay that's the whole page bestie, hope you ate it up 💖 and for the cute sign-off: this page is for perl v5.40.0, dated 2024-09-13, and it's Tangence::Server(3pm) — go build something iconic with it, fr fr. 🎀✨🫶