NAME

POE::Component::Server::IRC::Backend - A POE component class that provides network connection abstraction for POE::Component::Server::IRC

SYNOPSIS

package MyIRCD;

use strict;
use warnings;
use base 'POE::Component::Server::IRC::Backend';

sub spawn {
    my ($package, %args) = @_;

    my $self = $package->create(prefix => 'ircd_', @_);

    # process %args ...

    return $self;
}

DESCRIPTION

POE::Component::Server::IRC::Backend - A POE component class that provides network connection abstraction for POE::Component::Server::IRC. It uses a plugin system. See POE::Component::Server::IRC::Plugin for details.

CONSTRUCTOR

`create`

Returns an object. Accepts the following parameters, all are optional:

'alias', a POE::Kernel alias to set;
'auth', set to a false value to globally disable IRC authentication, default is auth is enabled;
'antiflood', set to a false value to globally disable flood protection, default is true;
'prefix', this is the prefix that is used to generate event names that the component produces. The default is 'ircd_'.
'states', an array reference of extra objects states for the IRC daemon's POE sessions. The elements can be array references of states as well as hash references of state => handler pairs.
'plugin_debug', set to a true value to print plugin debug info. Default is false.
'options', a hashref of options to POE::Session
'raw_events', whether to send raw events. False by default. Can be enabled later with raw_events;
'sslify_options', an array reference of items that are passed to POE::Component::SSLify SSLify_Options. Used to supply x509 certificate and key;

If the component is created from within another session, that session will be automagcially registered with the component to receive events and get an 'ircd_backend_registered' event.

METHODS

General

`shutdown`

Takes no arguments. Terminates the component. Removes all listeners and connectors. Disconnects all current client and server connections. This is a shorthand for $ircd->yield('shutdown').

`session_id`

Inherited from POE::Component::Syndicator

Takes no arguments. Returns the ID of the component's session. Ideal for posting events to the component.

`session_alias`

Inherited from POE::Component::Syndicator

Takes no arguments. Returns the session alias that has been set through create's 'alias' argument.

`yield`

Inherited from POE::Component::Syndicator

This method provides an alternative object based means of posting events to the component. First argument is the event to post, following arguments are sent as arguments to the resultant post.

`call`

Inherited from POE::Component::Syndicator

This method provides an alternative object based means of calling events to the component. First argument is the event to call, following arguments are sent as arguments to the resultant call.

`delay`

Inherited from POE::Component::Syndicator

This method provides a way of posting delayed events to the component. The first argument is an arrayref consisting of the delayed command to post and any command arguments. The second argument is the time in seconds that one wishes to delay the command being posted.

Returns an alarm ID that can be used with delay_remove to cancel the delayed event. This will be undefined if something went wrong.

`delay_remove`

Inherited from POE::Component::Syndicator

This method removes a previously scheduled delayed event from the component. Takes one argument, the alarm_id that was returned by a delay method call.

Returns an arrayref that was originally requested to be delayed.

`send_event`

Inherited from POE::Component::Syndicator

Sends an event through the component's event handling system. These will get processed by plugins then by registered sessions. First argument is the event name, followed by any parameters for that event.

`send_event_next`

Inherited from POE::Component::Syndicator

This sends an event right after the one that's currently being processed. Useful if you want to generate some event which is directly related to another event so you want them to appear together. This method can only be called when POE::Component::IRC is processing an event, e.g. from one of your event handlers. Takes the same arguments as send_event.

`send_event_now`

Inherited from POE::Component::Syndicator

This will send an event to be processed immediately. This means that if an event is currently being processed and there are plugins or sessions which will receive it after you do, then an event sent with send_event_now will be received by those plugins/sessions before the current event. Takes the same arguments as send_event.

`raw_events`

If called with a true value, raw events (ircd_raw_input and ircd_raw_output) will be enabled.

Connections

`antiflood`

Takes two arguments, a connection id and true/false value. If value is specified antiflood protection is enabled or disabled accordingly for the specified connection. If a value is not specified the current status of antiflood protection is returned. Returns undef on error.

`compressed_link`

Takes two arguments, a connection id and true/false value. If a value is specified, compression will be enabled or disabled accordingly for the specified connection. If a value is not specified the current status of compression is returned. Returns undef on error.

`disconnect`

Requires on argument, the connection id you wish to disconnect. The component will terminate the connection the next time that the wheel input is flushed, so you may send some sort of error message to the client on that connection. Returns true on success, undef on error.

`connection_exists`

Requires one argument, a connection id. Returns true value if the connection exists, false otherwise.

`connection_info`

Takes one argument, a connection_id. Returns a list consisting of: the IP address of the peer; the port on the peer; our socket address; our socket port. Returns undef on error.

my ($peeraddr, $peerport, $sockaddr, $sockport) = $ircd->connection_info($conn_id);

`add_denial`

Takes one mandatory argument and one optional. The first mandatory argument is an address or CIDR as understood by Net::CIDR::cidrvalidate that will be used to check connecting IP addresses against. The second optional argument is a reason string for the denial.

`del_denial`

Takes one mandatory argument, an address or CIDR as understood by Net::CIDR::cidrvalidate to remove from the current denial list.

`denied`

Takes one argument, an IP address. Returns true or false depending on whether that IP is denied or not.

`add_exemption`

Takes one mandatory argument, an address or CIDR as understood by Net::CIDR::cidrvalidate that will be checked against connecting IP addresses for exemption from denials.

`del_exemption`

Takes one mandatory argument, an address or CIDR as understood by Net::CIDR::cidrvalidate to remove from the current exemption list.

`exempted`

Takes one argument, an IP address. Returns true or false depending on whether that IP is exempt from denial or not.

Plugins

`pipeline`

Inherited from Object::Pluggable

Returns the Object::Pluggable::Pipeline object.

`plugin_add`

Inherited from Object::Pluggable

Accepts two arguments:

The alias for the plugin
The actual plugin object
Any number of extra arguments

The alias is there for the user to refer to it, as it is possible to have multiple plugins of the same kind active in one Object::Pluggable object.

This method goes through the pipeline's push() method, which will call $plugin->plugin_register($pluggable, @args).

Returns the number of plugins now in the pipeline if plugin was initialized, undef/an empty list if not.

`plugin_del`

Inherited from Object::Pluggable

Accepts the following arguments:

The alias for the plugin or the plugin object itself
Any number of extra arguments

This method goes through the pipeline's remove() method, which will call $plugin->plugin_unregister($pluggable, @args).

Returns the plugin object if the plugin was removed, undef/an empty list if not.

`plugin_get`

Inherited from Object::Pluggable

Accepts the following arguments:

The alias for the plugin

This method goes through the pipeline's get() method.

Returns the plugin object if it was found, undef/an empty list if not.

`plugin_list`

Inherited from Object::Pluggable

Takes no arguments.

Returns a hashref of plugin objects, keyed on alias, or an empty list if there are no plugins loaded.

`plugin_order`

Inherited from Object::Pluggable

Takes no arguments.

Returns an arrayref of plugin objects, in the order which they are encountered in the pipeline.

`plugin_register`

Inherited from Object::Pluggable

Accepts the following arguments:

The plugin object
The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
The event name[s] to watch

The event names can be as many as possible, or an arrayref. They correspond to the prefixed events and naturally, arbitrary events too.

You do not need to supply events with the prefix in front of them, just the names.

It is possible to register for all events by specifying 'all' as an event.

Returns 1 if everything checked out fine, undef/an empty list if something is seriously wrong.

`plugin_unregister`

Inherited from Object::Pluggable

Accepts the following arguments:

The plugin object
The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
The event name[s] to unwatch

The event names can be as many as possible, or an arrayref. They correspond to the prefixed events and naturally, arbitrary events too.

You do not need to supply events with the prefix in front of them, just the names.

It is possible to register for all events by specifying 'all' as an event.

Returns 1 if all the event name[s] was unregistered, undef if some was not found.

INPUT EVENTS

These are POE events that the component will accept:

`register`

Inherited from POE::Component::Syndicator

Takes N arguments: a list of event names that your session wants to listen for, minus the irc_ prefix.

$ircd->yield('register', qw(connected disconnected));

The special argument 'all' will register your session for all events. Registering will generate an ircd_registered event that your session can trap.

`unregister`

Inherited from POE::Component::Syndicator

Takes N arguments: a list of event names which you don't want to receive. If you've previously done a register for a particular event which you no longer care about, this event will tell the component to stop sending them to you. (If you haven't, it just ignores you. No big deal.)

If you have registered with 'all', attempting to unregister individual events such as 'connected', etc. will not work. This is a 'feature'.

`add_listener`

Takes a number of arguments. Adds a new listener.

'port', the TCP port to listen on. Default is a random port;
'auth', enable or disable auth sub-system for this listener. Enabled by default;
'bindaddr', specify a local address to bind the listener to;
'listenqueue', change the SocketFactory's ListenQueue;
'usessl', whether the listener should use SSL. Default is false;
'antiflood', whether the listener should use flood protection. Defaults is true;
'idle', the time, in seconds, after which a connection will be considered idle. Defaults is 180.

`del_listener`

Takes one of the following arguments:

'listener', a previously returned listener ID;
'port', a listening port;

The listener will be deleted. Note: any connected clients on that port will not be disconnected.

`add_connector`

Takes two mandatory arguments, 'remoteaddress' and 'remoteport'. Opens a TCP connection to specified address and port.

'remoteaddress', hostname or IP address to connect to;
'remoteport', the TCP port on the remote host;
'bindaddress', a local address to bind from (optional);
'idle', the time, in seconds, after which a connection will be considered idle. Defaults is 180;
'usessl', whether the connection should use SSL. Default is false;

`send_output`

Takes a hashref and one or more connection IDs.

$ircd->yield(
    'send_output',
    {
        prefix  => 'blah!~blah@blah.blah.blah',
        command => 'PRIVMSG',
        params  => ['#moo', 'cows go moo, not fish :D']
    },
    @list_of_connection_ids,
);

`shutdown`

Inherited from POE::Component::Syndicator

Takes no arguments. Terminates the component. Removes all listeners and connectors. Disconnects all current client and server connections.

OUTPUT EVENTS

These following events are sent to interested sessions.

`ircd_registered`

Inherited from POE::Component::Syndicator

Emitted: when a session registers with the component;

Target: the registering session;

Args:

ARG0: the component's object;

`ircd_connection`

Emitted: when a client connects to one of the component's listeners;

Target: all plugins and registered sessions

Args:

ARG0: the conn id;
ARG1: their ip address;
ARG2: their tcp port;
ARG3: our ip address;
ARG4: our socket port;
ARG5: a boolean indicating whether the client needs to be authed
ARG6: a boolean indicating whether the client is securely connected

`ircd_auth_done`

Emitted: after a client has connected and the component has validated hostname and ident;

Target: Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, a HASHREF with the following keys: 'ident' and 'hostname';

`ircd_listener_add`

Emitted: on a successful add_listener call;

Target: all plugins and registered sessions;

Args:

ARG0, the listening port;
ARG1, the listener id;
ARG2, the listening address;
ARG3, whether SSL is in use;

`ircd_listener_del`

Emitted: on a successful del_listener call;

Target: all plugins and registered sessions;

Args:

ARG0, the listening port;
ARG1, the listener id;
ARG2, the listener address;

`ircd_listener_failure`

Emitted: when a listener wheel fails;

Target: all plugins and registered sessions;

Args:

ARG0, the listener id;
ARG1, the name of the operation that failed;
ARG2, numeric value for $!;
ARG3, string value for $!;
ARG4, the port it tried to listen on;
ARG5, the address it tried to listen on;

`ircd_socketerr`

Emitted: on the failure of an add_connector call

Target: all plugins and registered sessions;

Args:

ARG0, a HASHREF containing the params that add_connector() was called with;
ARG1, the name of the operation that failed;
ARG2, numeric value for $!;
ARG3, string value for $!;

`ircd_connected`

Emitted: when the component establishes a connection with a peer;

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, their ip address;
ARG2, their tcp port;
ARG3, our ip address;
ARG4, our socket port;
ARG5, the peer's name;

`ircd_connection_flood`

Emitted: when a client connection is flooded;

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;

`ircd_connection_idle`

Emitted: when a client connection has not sent any data for a set period;

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, the number of seconds period we consider as idle;

`ircd_compressed_conn`

Emitted: when compression has been enabled for a connection

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;

`ircd_cmd_*`

Emitted: when a client or peer sends a valid IRC line to us;

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;

ARG1, a HASHREF containing the output record from POE::Filter::IRCD:

{
    prefix => 'blah!~blah@blah.blah.blah',
    command => 'PRIVMSG',
    params  => [ '#moo', 'cows go moo, not fish :D' ],
    raw_line => ':blah!~blah@blah.blah.blah.blah PRIVMSG #moo :cows go moo, not fish :D'
}

`ircd_raw_input`

Emitted: when a line of input is received from a connection

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, the raw line of input

`ircd_raw_output`

Emitted: when a line of output is sent over a connection

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, the raw line of output

`ircd_disconnected`

Emitted: when a client disconnects;

Target: all plugins and registered sessions;

Args:

ARG0, the connection id;
ARG1, the error or reason for disconnection;

`ircd_shutdown`

Inherited from POE::Component::Syndicator

Emitted: when the component has been asked to shutdown

Target: all registered sessions;

Args:

ARG0: the session ID of the requesting component

`ircd_delay_set`

Inherited from POE::Component::Syndicator

Emitted: on a successful addition of a delayed event using the delay method

Target: all plugins and registered sessions;

Args:

ARG0: the alarm id which can be used later with delay_remove
ARG1..$#_: subsequent arguments are those which were passed to delay

`ircd_delay_removed`

Inherited from POE::Component::Syndicator

Emitted: when a delayed command is successfully removed

Target: all plugins and registered sessions;

Args:

ARG0: the alarm id which was removed
ARG1..$#_: subsequent arguments are those which were passed to delay

`ircd_plugin_add`

Inherited from Object::Pluggable

Emitted: when a new plugin is added to the pipeline

Target: all plugins and registered sessions;

Args:

ARG0: the plugin alias
ARG1: the plugin object

`ircd_plugin_del`

Inherited from Object::Pluggable

Emitted: when a plugin is removed from the pipeline

Target: all plugins and registered sessions;

Args:

ARG0: the plugin alias
ARG1: the plugin object

`ircd_plugin_error`

Inherited from Object::Pluggable

Emitted: when an error occurs while executing a plugin handler

Target: all plugins and registered sessions;

Args:

ARG0: the error message
ARG1: the plugin alias
ARG2: the plugin object

AUTHOR

Chris 'BinGOs' Williams

LICENSE

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

create

METHODS

General

shutdown

session_id

session_alias

yield

call

delay

delay_remove

send_event

send_event_next

send_event_now

raw_events

Connections

antiflood

compressed_link

disconnect

connection_exists

connection_info

add_denial

del_denial

denied

add_exemption

del_exemption

exempted

Plugins

pipeline

plugin_add

plugin_del

plugin_get

plugin_list

plugin_order

plugin_register

plugin_unregister

INPUT EVENTS

register

unregister

add_listener

del_listener

add_connector

send_output

shutdown

OUTPUT EVENTS

ircd_registered

ircd_connection

ircd_auth_done

ircd_listener_add

ircd_listener_del

ircd_listener_failure

ircd_socketerr

ircd_connected

ircd_connection_flood

ircd_connection_idle

ircd_compressed_conn

ircd_cmd_*

ircd_raw_input

ircd_raw_output

ircd_disconnected

ircd_shutdown

ircd_delay_set

ircd_delay_removed

ircd_plugin_add

ircd_plugin_del

ircd_plugin_error

AUTHOR

LICENSE

SEE ALSO

Module Install Instructions

`create`

`shutdown`

`session_id`

`session_alias`

`yield`

`call`

`delay`

`delay_remove`

`send_event`

`send_event_next`

`send_event_now`

`raw_events`

`antiflood`

`compressed_link`

`disconnect`

`connection_exists`

`connection_info`

`add_denial`

`del_denial`

`denied`

`add_exemption`

`del_exemption`

`exempted`

`pipeline`

`plugin_add`

`plugin_del`

`plugin_get`

`plugin_list`

`plugin_order`

`plugin_register`

`plugin_unregister`

`register`

`unregister`

`add_listener`

`del_listener`

`add_connector`

`send_output`

`shutdown`

`ircd_registered`

`ircd_connection`

`ircd_auth_done`

`ircd_listener_add`

`ircd_listener_del`

`ircd_listener_failure`

`ircd_socketerr`

`ircd_connected`

`ircd_connection_flood`

`ircd_connection_idle`

`ircd_compressed_conn`

`ircd_cmd_*`

`ircd_raw_input`

`ircd_raw_output`

`ircd_disconnected`

`ircd_shutdown`

`ircd_delay_set`

`ircd_delay_removed`

`ircd_plugin_add`

`ircd_plugin_del`

`ircd_plugin_error`