Abandoned

sungo d48bb41f58 import from tarball 11 years ago
ex d48bb41f58 import from tarball 11 years ago
lib d48bb41f58 import from tarball 11 years ago
t d48bb41f58 import from tarball 11 years ago
Changes d48bb41f58 import from tarball 11 years ago
LICENSE d48bb41f58 import from tarball 11 years ago
MANIFEST d48bb41f58 import from tarball 11 years ago
MANIFEST.SKIP d48bb41f58 import from tarball 11 years ago
META.yml d48bb41f58 import from tarball 11 years ago
Makefile.PL d48bb41f58 import from tarball 11 years ago
README d48bb41f58 import from tarball 11 years ago
VERSION d48bb41f58 import from tarball 11 years ago

README

NAME
POE::Component::ControlPort - network control port for POE applications

SYNOPSIS
use POE;
use Getopt::Long;

use POE::Component::ControlPort;
use POE::Component::ControlPort::Command;

my @commands = (
{
help_text => 'My command',
usage => 'my_command [ arg1, arg2 ]',
topic => 'custom',
name => 'my_command',
command => sub {
my %input = @_;

local @ARGV = @{ $input{args} };
GetOptions( ... );
},
}
);


POE::Component::ControlPort->create(
local_address => '127.0.0.1',
local_port => '31337',

# optional...
hostname => 'pie.pants.org',
appname => 'my perl app',

commands => \@commands,

poe_debug => 1,
);

# other poe sessions or whatever ...

POE::Kernel->run();

DESCRIPTION
When building network applications, it is often helpful to have a
network accessible control and diagnostic interface. This module
provides such an interface for POE applications. By default, it provides
a fairly limited set of commands but is easily extended to provide
whatever command set you require. In addition, if
"POE::Component::DebugShell" version 1.018 or above is installed, a set
of POE debug commands will be loaded.

GETTING STARTED
The utility of a network accessible controlport is limited only by the
commands you allow access to. A controlport with only a status command
isn't very useful. Defining commands is easy.

DEFINING COMMANDS
my @commands = (
{
help_text => 'My command',
usage => 'my_command [ arg1, arg2 ]',
topic => 'custom',
name => 'my_command',
command => sub {
my %input = @_;

local @ARGV = @{ $input{args} };
GetOptions( ... );
},
}
);

A command is defined by a hash of metadata and a subroutine reference.
The metadata helps to group commands into functional units as well as
display help and usage information for the confused user. The meat of a
command, obviously, is the subroutine reference which makes up the
'command' part of the metadata.

The subroutine reference is executed every time a user issues the
command name that is assigned for it. Any text returned from the
subroutine will be printed out to the user in the control port. The
subroutine's arguments are a hash of data about the command invocation.

* args

This hash element is a list of arguments the user passed in to the
command. It is suggested that you assign this list to @ARGV and use
Getopt::Long and friends to parse the arguments.

* oob

This hash element contains a hash of out of band data about the
transaction. It is populated with hostname, appname, client_addr,
and client_port.

LAUNCHING THE PORT
POE::Component::ControlPort->create(
local_address => '127.0.0.1',
local_port => '31337',

# optional...
hostname => 'pie.pants.org',
appname => 'my perl app',

commands => \@commands,

poe_debug => 1,
)

The "create()" method in the "POE::Component::ControlPort" namespace is
used to create and launch the control port. There are several parameters
available to "create()".

* local_address

Mandatory. The address on which the control port should listen.

* local_port

Mandatory. The port on which the control port should listen.

* commands

Optional (but boring if not provided). An array of command hashes.
See "DEFINING COMMANDS" above.

* hostname

Optional. Mostly for display in the control port itself. Will
probably be used for other things in the future.

* appname

Optional. The name of this application, defaulting to
"basename($0)". This is used by TCPwrappers to determine if the
connecting user is allowed to connect. This is also used as the
master alias for the control port session.

* poe_debug

Optional. Defaults to 0. If true, attempts to load commands from
POE::Component::DebugShell if said module is available and of the
appropriate version.

SHUTTING DOWN
The control port responds to a "shutdown" event to the appname given
during control port creation. This event will cause the immediate
shutdown of all connections and the termination of the listener.

REQUIREMENTS
The following perl modules are required for this module to work
properly.

* Authen::Libwrap

* Carp

* File::Basename

* POE

* Params::Validate

* Sys::Hostname

AUTHOR
Matt Cashner (sungo@pobox.com)

REVISION
$Rev: 266 $

DATE
$Date: 2004-05-09 22:59:17 -0400 (Sun, 09 May 2004) $

LICENSE
Copyright (c) 2004, Matt Cashner

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.