Initial commit and approved by Y!

LICENSE

@@ -0,0 +1,127 @@
+ The "Artistic License"
+
+				Preamble
+
+The intent of this document is to state the conditions under which a
+Package may be copied, such that the Copyright Holder maintains some
+semblance of artistic control over the development of the package,
+while giving the users of the package the right to use and distribute
+the Package in a more-or-less customary fashion, plus the right to make
+reasonable modifications.
+
+Definitions:
+
+	"Package" refers to the collection of files distributed by the
+	Copyright Holder, and derivatives of that collection of files
+	created through textual modification.
+
+	"Standard Version" refers to such a Package if it has not been
+	modified, or has been modified in accordance with the wishes
+	of the Copyright Holder as specified below.
+
+	"Copyright Holder" is whoever is named in the copyright or
+	copyrights for the package.
+
+	"You" is you, if you're thinking about copying or distributing
+	this Package.
+
+	"Reasonable copying fee" is whatever you can justify on the
+	basis of media cost, duplication charges, time of people involved,
+	and so on.  (You will not be required to justify it to the
+	Copyright Holder, but only to the computing community at large
+	as a market that must bear the fee.)
+
+	"Freely Available" means that no fee is charged for the item
+	itself, though there may be fees involved in handling the item.
+	It also means that recipients of the item may redistribute it
+	under the same conditions they received it.
+
+1. You may make and give away verbatim copies of the source form of the
+Standard Version of this Package without restriction, provided that you
+duplicate all of the original copyright notices and associated disclaimers.
+
+2. You may apply bug fixes, portability fixes and other modifications
+derived from the Public Domain or from the Copyright Holder.  A Package
+modified in such a way shall still be considered the Standard Version.
+
+3. You may otherwise modify your copy of this Package in any way, provided
+that you insert a prominent notice in each changed file stating how and
+when you changed that file, and provided that you do at least ONE of the
+following:
+
+    a) place your modifications in the Public Domain or otherwise make them
+    Freely Available, such as by posting said modifications to Usenet or
+    an equivalent medium, or placing the modifications on a major archive
+    site such as uunet.uu.net, or by allowing the Copyright Holder to include
+    your modifications in the Standard Version of the Package.
+
+    b) use the modified Package only within your corporation or organization.
+
+    c) rename any non-standard executables so the names do not conflict
+    with standard executables, which must also be provided, and provide
+    a separate manual page for each non-standard executable that clearly
+    documents how it differs from the Standard Version.
+
+    d) make other distribution arrangements with the Copyright Holder.
+
+4. You may distribute the programs of this Package in object code or
+executable form, provided that you do at least ONE of the following:
+
+    a) distribute a Standard Version of the executables and library files,
+    together with instructions (in the manual page or equivalent) on where
+    to get the Standard Version.
+
+    b) accompany the distribution with the machine-readable source of
+    the Package with your modifications.
+
+    c) give non-standard executables non-standard names, and clearly
+    document the differences in manual pages (or equivalent), together
+    with instructions on where to get the Standard Version.
+
+    d) make other distribution arrangements with the Copyright Holder.
+
+5. You may charge a reasonable copying fee for any distribution of this
+Package.  You may charge any fee you choose for support of this
+Package.  You may not charge a fee for this Package itself.  However,
+you may distribute this Package in aggregate with other (possibly
+commercial) programs as part of a larger (possibly commercial) software
+distribution provided that you do not advertise this Package as a
+product of your own.  You may embed this Package's interpreter within
+an executable of yours (by linking); this shall be construed as a mere
+form of aggregation, provided that the complete Standard Version of the
+interpreter is so embedded.
+
+6. The scripts and library files supplied as input to or produced as
+output from the programs of this Package do not automatically fall
+under the copyright of this Package, but belong to whoever generated
+them, and may be sold commercially, and may be aggregated with this
+Package.  If such scripts or library files are aggregated with this
+Package via the so-called "undump" or "unexec" methods of producing a
+binary executable image, then distribution of such an image shall
+neither be construed as a distribution of this Package nor shall it
+fall under the restrictions of Paragraphs 3 and 4, provided that you do
+not represent such an executable image as a Standard Version of this
+Package.
+
+7. C subroutines (or comparably compiled subroutines in other
+languages) supplied by you and linked into this Package in order to
+emulate subroutines and variables of the language defined by this
+Package shall not be considered part of this Package, but are the
+equivalent of input as in Paragraph 6, provided these subroutines do
+not change the language in any way that would cause it to fail the
+regression tests for the language.
+
+8. Aggregation of this Package with a commercial distribution is always
+permitted provided that the use of this Package is embedded; that is,
+when no overt attempt is made to make this Package's interfaces visible
+to the end user of the commercial distribution.  Such use shall not be
+construed as a distribution of this Package.
+
+9. The name of the Copyright Holder may not be used to endorse or promote
+products derived from this software without specific prior written permission.
+
+10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+				The End

README

@@ -0,0 +1,161 @@
+NAME
+    App::Foca::Server - Foca server
+
+DESCRIPTION
+    Foca is an application (a HTTP server using HTTP::Daemon) that allows
+    the execution of pre-defined commands via, obviously, HTTP.
+
+    Well, lets suppose you have a log parser on all your servers and you are
+    in need to parse all of them, the common way would be to ssh to each
+    host (can be as simple as ssh'ing to each host or using a multiplex
+    tool) and execute your parser, but what if your SSH keys or the keys of
+    a user are not there? It will be a heck of pain to enter your password
+    hundred of times or lets imagine you want to parse your logs via some
+    automation (like doing it from an IRC bot or tied to your monitoring
+    solution).. then the problem comes more complex with SSH and private
+    keys. With Foca you don't need to worry about those things, the command
+    will get executed and the output will be returned as a HTTP response.
+
+    All commands that Foca knows about it are listed in a YAML file. Foca
+    uses a default timeout value for all commands but with this YAML file
+    you can give a specific timeout to a specific command. All commands are
+    executed with IPC (open3).
+
+    Now the question is.. is Foca secure? Well it depends on you. Depends if
+    you run it as non-root user and the commands you define. Foca will try
+    to do things to protect, for example it will reject all requests that
+    have pipes (|), I/O redirection (>, <, <<, >>), additionally the HTTP
+    request will be validated before it gets executed via the call of
+    "validate_request()" (App::Foca returns true all the time so if you want
+    to add extra functionality please create a subclass and re-define the
+    method).
+
+EXAMPLE
+        my $server = App::Foca::Server->new(
+                port                => $port,
+                commands_file       => $commands,
+                commands_timeout    => $timeout,
+                debug               => $debug);
+
+        $server->run_server();
+
+EXAMPLE COMMANDS FILE
+        commands_dirs:
+            - /some/path/over/there/bin
+
+        commands:
+            df_path:
+            cmd: '/bin/df {%foca_args%} | tail -n1'
+        uptime:
+            cmd: '/usr/bin/uptime'
+        'true':
+            cmd: '/bin/true'
+
+    The way the example commands file work is: First it will look if there
+    is a *commands_dir* key, this key should have a list of directories
+    (that means it should be an array reference), Foca will look for all
+    executables inside the given directories and add them into memory.
+    Second, it will look for the *commands* key, this one should be a hash
+    where each key is the name of the command and it should have at least a
+    *cmd* key which value should be the *real* command to execute.
+
+    Please note that when you use the *commands_dir*, Foca will use the
+    basename of each executable as the name of the command so if you have
+    /usr/local/foo, the foca command will be *foo* while the command it will
+    execute will be */usr/local/foo*.
+
+    Also, you can override commands found in *commands_dir* via *commands*,
+    so going back to our /usr/local/foo example, you can have this
+    executable in your /usr/local directory but also have a *foo* command
+    defined in *commands*, the one that is defined in *commands* will be the
+    one that will be used by Foca.
+
+    There are two ways to update the list of commands once the server
+    started: One is by obviously restarting it and the other one is via
+    localhost send a HTTP request to localhost:yourport/reload.
+
+Attributes
+    commands_file
+        YAML file with the supported commands.
+
+    commands
+        Hash reference with a list of supported commands. Basically the
+        content of "commands_file".
+
+    port
+        Where to listen for requests?
+
+    commands_timeout
+        Global timeout for all commands. Default to 1min (60 seconds).
+
+    tmp_dir
+        Temporary directory, for cache.
+
+    debug
+        Debug/verbose mode, turned off by default.
+
+    server
+        App::Foca::Server::HTTP object.
+
+    cache
+        For mmap cache (so we can share cache across processes).
+
+Methods
+  run_server()
+    Runs the HTTP::Daemon server. it forks on each request.
+
+  prepare_status_response()
+    Prepares a response (HTTP::Response) for the /status request. /status
+    requests returns some stats about Foca server, such as: number of active
+    connections, number of closed/zombie connections (user connected and
+    left the connection open with a process that is no longer needed).
+
+  prepare_foca_response($connection, $request)
+    Prepares a response (HTTP::Response) for a given foca request
+    (HTTP::Request).
+
+  build_response($code, $body)
+    Builds a HTTP response ("HTTP::Response") based on the given HTTP status
+    code and optionally adds a body.
+
+    Returns a "HTTP::Response" so it can be send via the opened connection.
+
+  validate_request($command, $request)
+    re-define this method if you want to add some extra security. By default
+    all requests are valid at this point.
+
+  run_cmd($connection, $name, $cmd, $params)
+    Runs whatever the command is and sets a timeout to it. If it takes too
+    long then it will try to kill the process.
+
+    Depending on the settings given to the command it will return the STDOUT
+    or STDERR or even both. The rules are:
+
+    1. On success it will look for STDOUT, if nothing is there then it looks
+    in STDERR. If nothing is foudn in STDERR and STDOUT then an empty string
+    is returned.
+    2. On error it will look for STDERR first, if nothing is there then it
+    looks in STDOUT. If nothing is there then it returns an empty string.
+
+    Both STDOUT and STDERR can be returned if the command is defined as
+    follows:
+
+        server_uptime:
+            cmd: '/usr/bin/uptime'
+            capture_all: 'y'
+
+  load_commands()
+    Load the commands YAML file and stores it in memory with Cache::FastMnap
+
+COPYRIGHT
+    Copyright (c) 2010-2012 Yahoo! Inc. All rights reserved.
+
+LICENSE
+    This program is free software. You may copy or redistribute it under the
+    same terms as Perl itself. Please see the LICENSE file included with
+    this project for the terms of the Artistic License under which this
+    project is licensed.
+
+AUTHORS
+    Pablo Fischer (pablo@pablo.com.mx)
+