NAME
PACKAGES
SYNOPSIS
- DTA::CAB::Server::HTTP::UNIX Synopsis
- DTA::CAB::Server::HTTP::UNIX::ClientConn Synopsis
DESCRIPTION
- DTA::CAB::Server::HTTP::UNIX Description
AUTHOR
COPYRIGHT AND LICENSE
SEE ALSO

NAME

DTA::CAB::Server::HTTP::UNIX - DTA::CAB standalone HTTP server using HTTP::Daemon::UNIX

PACKAGES

DTA::CAB::Server::HTTP::UNIX
DTA::CAB::Server::HTTP::UNIX::ClientConn

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DTA::CAB::Server::HTTP::UNIX;

DTA::CAB::Server::HTTP::UNIX Synopsis

 ##========================================================================
 ## Constructors etc.
 
 $obj = CLASS_OR_OBJ->new(%args);
 undef = $obj->DESTROY();
 
 ##========================================================================
 ## Methods: HTTP server API
 
 $str = $srv->socketLabel();
 $str = $srv->daemonLabel();
 $bool = $srv->canBindSocket();
 $class = $srv->daemonClass();
 $class_or_undef = $srv->clientClass();
 
 ##========================================================================
 ## Methods: Generic Server API
 
 ## $rc = $srv->prepareLocal();
 ## $bool = $srv->prepareRelay();
 
 ##========================================================================
 ## Methods: Local: spawn and reap
 
 \&reaper = $srv->reaper();

DTA::CAB::Server::HTTP::UNIX::ClientConn Synopsis

 ($pid,$uid,$gid) = $sock->peercred();
 \%env = $sock->peerenv();
 $str = $sock->peerstr();
 $host = peerhost();
 $port = peerport();

DESCRIPTION

DTA::CAB::Server::HTTP::UNIX Description

Globals

Variable: @ISA: DTA::CAB::Server::HTTP::UNIX inherits from DTA::CAB::Server::HTTP, and supports the DTA::CAB::Server::HTTP and DTA::CAB::Server APIs.

Constructors etc.

new

 $srv = CLASS_OR_OBJ->new(%args);

Arguments and object structure are mostly inherited from DTA::CAB::Server::HTTP. Local overrides and extensions:

 (
  ##-- DTA::CAB::Server::HTTP overrides
  daemonArgs => \%daemonArgs,   ##-- overrides for HTTP::Daemon::UNIX->new(); default={Local=>'/tmp/dta-cab.sock'}
  ##
  ##-- DTA::CAB::Server::HTTP::UNIX extensions
  socketPerms => $mode,         ##-- socket permissions as an octal string (default='0666')
  socketUser  => $user,         ##-- socket user or uid (root only; default=undef: current user)
  socketGroup => $group,        ##-- socket group or gid (default=undef: current group)
  _socketPath => $path,         ##-- bound socket path (for unlink() on destroy)
  relayCmd    => \@cmd,         ##-- TCP relay command-line for exec() (default=[qw(socat ...)], see prepareRelay())
  relayAddr   => $addr,         ##-- TCP relay address to bind (default=$daemonArgs{LocalAddr}, see prepareRelay())
  relayPort   => $port,         ##-- TCP relay address to bind (default=$daemonArgs{LocalPort}, see prepareRelay())
  relayPid    => $pid,          ##-- child PID for TCP relay process (sockrelay.perl / socat; see prepareRelay())

DESTROY

 undef = $srv->DESTROY();

override unlinks any UNIX socket $srv->{_socketPath} if defined.

Methods: HTTP server API

socketLabel

 $str = $srv->socketLabel();

returns symbolic label for bound socket address; override returns socket path $srv->{daemonArgs}{Local}.

daemonLabel

 $str = $srv->daemonLabel();

returns symbolic label for running daemon, override returns socket path $srv->{daemon}->hostpath().

canBindSocket

 $bool = $srv->canBindSocket();

returns true iff socket can be bound; should set $! on error; override just tries to bind the UNIX socket specified by $srv->{daemonArgs}{Local}.

daemonClass

 $class = $srv->daemonClass();

get HTTP::Daemon class, override returns 'HTTP::Daemon::UNIX'.

clientClass

 $class_or_undef = $srv->clientClass();

get class for client connections, override returns 'DTA::CAB::Server::HTTP::UNIX::ClientConn'.

Methods: Generic Server API

prepareLocal

 $rc = $srv->prepareLocal();

subclass-local initialization; override calls superclass prepareLocal(), sets up UNIX socket ownership and permissions, and calls the prepareRelay() method to optionally set up a TCP relay subprocess.

prepareRelay

 $bool = $srv->prepareRelay();

Starts a TCP listener subprocess to relay incoming TCP messages to the server's UNIX socket if requested. A TCP listener process will be started on ADDR:PORT if a TCP address+port pair (ADDR,PORT) is specified in $srv->{daemonArgs} (keys "LocalAddr","LocalPort") or $srv itself (keys "relayAddr","relayPort"). You must have the socat(1) program installed on your system for this to work.

Methods: Local: spawn and reap

reaper

 \&reaper = $srv->reaper();

Zombie-harvesting code; installed to local %SIG. Override returns a reaper sub which die()s if it harvests the TCP relay subprocess started by the prepareRelay() method.

PACKAGE: DTA::CAB::Server::HTTP::UNIX::ClientConn

Variable: @ISA

DTA::CAB::Server::HTTP::UNIX inherits from HTTP::Daemon::ClientConn and should support most HTTP::Daemon::ClientConn methods.

peercred

 ($pid,$uid,$gid) = $sock->peercred();

Gets UNIX socket peer credentials; returns (-1,-1,-1) on failure.

peerenv

 \%env = $sock->peerenv();
 \%env = $sock->peerenv($pid);

Attempts to retrieve environment variables for peer process, if possible. Uses cached value in ${*sock}{peerenv} if present, otherwise attempts to open and parse /proc/$pid/environ. Returns undef on failure.

peerstr

 $str = $sock->peerstr();
 $str = $sock->peerstr($uid,$gid,$pid);

Returns stringified unix peer credentials, "${USER}.${GROUP}[${PID}]".

peerhost

 $host = peerhost();

For relayed connections, gets underlying TCP peer via socat environment (INET emulation); for unix connections, returns UNIX credentials as as for peerstr().

peerport

 $port = peerport();

For relayed connections, gets underlying TCP port via socat environment (INET emulation); for unix connections, returns socket path:

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.1 or, at your option, any later version of Perl 5 you may have available.