NAME
    OpenResty - General-purpose web service platform for web applications

VERSION
    This document describes OpenResty 0.1.4 released on March 14, 2008.

DESCRIPTION
    This module implements the server-side OpenResty web service protocol.
    It provides scriptable and extensible web services for both server-side
    and client-side (pure AJAX) web applications.

    Currently this module can serve as a public web interface to a
    distributive or desktop PostgreSQL database system. In particular, it
    provides roles, models, views, actions, captchas, the minisql language,
    and many more to the web users.

    Note that OpenResty is *not* a web application framework like Jifty.
    Rather, it can serve as a component in many existing web application
    frameworks.

    We're already running an instance of the OpenResty server on our Yahoo!
    China's production machines:

    <http://resty.eeeeworks.org/=/version>

    And there're several (pure-client-side) web sites alreadying taking
    advantage of the services:

    agentzh's blog site
        <http://blog.agentzh.org>

    Yisou.com's BBS
        <http://www.yisou.com/opi/post.html>

    This library is still in pre-alpha stage and the API is still in flux.
    We're just following the "release early, releaes often" guideline. So
    please check back often ;)

INSTALLATION
    This is a basic guideline for settting up an OpenResty server on your
    own machine. Someone has succeeded in setting up one on Windows XP using
    ActivePerl 5.8.8. The normal development environment is Linux though. If
    you have any particular question, feel free to ask us by sending an
    email to the authors.

    1.  Grab the openresty package and unpack it to some place, let's say
        it's openresty.

    2.  Enter the openresty directory, run "perl Makefile.PL" to check
        missing dependencies:

            $ cd openresty
            $ perl Makefile.PL
            $ sudo make  # This will install missing dependencies
            $ make test  # run the test suite using the PgMocked backend

        For the PostgreSQL database, you need to prepare a PostgreSQL
        account (e.g. "agentzh"); and you need to create an empty database
        (e.g., "test"), and you need to create a stored precedure language
        named "plpgsql" for that database, contact your PostgreSQL DBA for
        it or read the PostgreSQL manual.

        Normally, the following commands are used:

            $ createdb test
            $ createuser -P agnetzh
            $ createlang plpgsql test

    3.  Edit your etc/site_openresty.conf file, change the configure
        settings under [backend] section according to your previous
        settings. The default settings look like this:

            [backend]
            recording=0
            # You should change the line below to type=Pg or type=PgFarm
            type=PgMocked
            host=localhost
            user=agentzh
            password=agentzh
            database=test

        Most of the time, you need to change "type=PgMocked" to "type=Pg",
        as well as the last 3 lines (unless you're using exactly the same
        user, password, and database name). The default "PgMocked" backend
        is a mocked PostgreSQL database which is useful only for testing
        purposes.

    4.  Give read/write access to lighttpd's log file (optional):

            $ chmod 777 /var/log/lighttpd/error.log
            $ chmod 777 /var/log/lighttpd

    5.  For the Pg backend, one needs to create the "anonymous" role in his
        database (like "test"):

            $ createuser anonymouse test

    6.  Create a "tester" user account for our test suite in OpenResty (drop
        it if it already exists):

            $ bin/openresty deluser tester
            $ bin/openresty adduser tester

        Give a password (say, "password") to its Admin role. Update your
        etc/site_openresty.conf to reflect your these settings:

            [test_suite]
            use_http=0
            server=tester:password@localhost

        Now you can already run the test suite without a lighttpd server
        (but with a true Pg backend):

            $ make test

    7.  Sample lighttpd configuration:

            # lighttpd.conf

            server.modules              = (
                        "mod_fastcgi",
                        ...
            )

            fastcgi.server = (
                "/=" => (
                    "openresty" => (
                        "socket"       => "/tmp/openresty.socket",
                        "check-local"  => "disable",
                        "bin-path"     => "/PATH/TO/YOUR/bin/openresty",
                        "bin-environment" => (
                            "OPENRESTY_URL_PREFIX" => "",
                            "OPENRESTY_COMMAND" => "fastcgi",
                        ),
                        "min-procs"    => 1,
                        "max-procs"    => 5,
                        "max-load-per-proc" => 1,
                        "idle-timeout" => 20,
                    )
                )
            )

        And also make sure the following line is commented out:

            # url.access-deny            = ( "~", ".inc" )

    HOW TO TEST ONE SPECIFIC TEST SUITE FILE

    It's also possible to debug a simple .t file, for instance,

        make t/01-sanity.t -f dev.mk

    Or use the OPENRESTY_TEST_SERVER environment to test a remote OpenResty
    server, for example:

        OPENRESTY_TEST_SERVER=teser:password@10.62.136.86 prove -Ilib -r t

    where 10.62.136.86 is the IP (or hostname or URL) of your OpenResty
    server being tested.

    To test the Pg cluster rather than the desktop Pg, update your
    etc/site_openresty.conf:

        [backend]
        type=PgFarm

    and also set other items in the same group if necessary.

SOURCE TREE STRUCTURE
        bin/ directory is the where CGI entry openresty located
        doc/ directory containing OpenResty spec
        lib/OpenResty/ directory contain all the code needed to run OpenResty
        lib/OpenResty/OpenResty.pm contain the code stub for OpenResty protocol
        lib/OpenResty/Limits.pm are those hard limits located, we limit the number of different objects (model, row, view etc.) a user could create by default
        lib/OpenResty/Backend contain all the code to initialize OpenResty meta tables and code to access different database, for now we support Postgres stand alone database and 
        PostgreSQL cluster
        lib/OpenResty/Backend/Pg.pm OpenResty PostgreSQL stand alone database access code
        lib/OpenResty/Backend/PgFarm.pm OpenResty PostgreSQL cluster database access code
        lib/OpenResty/Handler contain all handler methods OpenResty supported, these methods are moved from lib/OpenResty.pm due to code refactor; 
                            method name looks like HTTP_METHOD_some_sub_name.
        lib/SQL classes/methods to generate SQL query (in string form), use OO to encapsulate SQL query generation
        lib/SQL/Statement.pm base class
        lib/SQL/Select.pm class and methods to generate SELECT statement
        lib/SQL/Insert.pm class and methods to generate INSERT statement
        lib/SQL/Update.pm class and methods to generate UPDATE statement
        lib/MiniSQL/ directory conatining our mini-sql parser code, now only SELECT support
        t/ directory containing OpenResty test suite, use `make test' to run the test, read above on how to setup test environment

SOURCE CONTROL
    For the very latest version of this module, check out the source from
    the SVN repos below:

    <http://svn.openfoundry.org/openapi/trunk>

    There is anonymous access to all. If you'd like a commit bit, please let
    us know. :)

TODO
    For the project's TODO list, please check out
    <http://svn.openfoundry.org/openapi/trunk/TODO>

BUGS
    There must be some serious bugs lurking somewhere given the current
    status of the implementation and test suite.

    Please report bugs or send wish-list to
    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=OpenResty>.

AUTHOR
    Agent Zhang (agentzh) "<agentzh at yahoo.cn>"
    Lei Yonghua (leiyh)
    Laser Henry (laser)
    Yu Ting (yuting) "<yuting at yahoo.cn>"

    For a complete list of the contributors, please see
    <http://svn.openfoundry.org/openapi/trunk/AUTHORS>.

License and Copyright
    Copyright (c) 2007, 2008 by Yahoo! China EEEE Works, Alibaba Inc.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO
    OpenResty::Spec::REST, OpenResty::CheatSheet, WWW::OpenResty,
    WWW::OpenResty::Simple.

