NAME
OpenResty - General-purpose web service platform for web applications
VERSION
This document describes OpenResty 0.5.12 released on Nov 20, 2009.
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
distributed or desktop PostgreSQL database system. In particular, it
provides roles, models, views, actions, captchas, the minisql language,
and many more to the web users.
"Another framework?" No, no, no, not all!
OpenResty is *not* a web application framework like Jifty or Catalyst.
Rather, it is
* A REST wrapper for relational databases
* A web runtime for 100% JavaScript web sites and other RIAs.
* A "meta web site" supporting other sites via web services.
* A handy personal or company database which can be accessed from
anywhere on the web.
* A (sort of) competitor for the Facebook Data Store API.
We're already running an instance of the OpenResty server on our Yahoo!
China's production machines:
<http://api.openresty.org/=/version>
And there're several (pure-client-side) web sites alreadying taking
advantage of the services:
OpenResty's admin site
<http://openresty.org/admin/>
agentzh's blog and EEEE Works' blog
<http://blog.agentzh.org>
<http://eeeeworks.org>
Yisou BBS
<http://www.yisou.com/opi/post.html>
See OpenResty::Spec::Overview for more detailed information.
OpenResty::CheatSheet also provides a good enough summary for the REST
interface.
You'll find my slides for the D2 conference interesting as well:
<http://agentzh.org/misc/openresty-d2.pdf>
or the original XUL version:
<http://agentzh.org/misc/openresty-d2/openresty-d2.xul> (Firefox
required)
Another good introduction to OpenResty's REST API is summerized in the
slides for my Y!ES talk and my Beijing Perl Workshop 2008 talk:
<http://agentzh.org/misc/openresty-yes.pdf>
and a more pretty (XUL) version can be got from here:
<http://agentzh.org/misc/openresty-yes/openresty-yes.xul> (Firefox
required)
There're also a few interesting discussions about OpenResty on my blog
site:
"OpenResty versus Google App Engine"
<http://blog.agentzh.org/#post-75>
"Google's crawlers captured OpenResty's API!"
<http://blog.agentzh.org/#post-79>
"Video for my D2 talk about OpenResty and its nifty apps"
<http://blog.agentzh.org/#post-81>
"The first yahoo.cn feature that is powered by OpenResty"
<http://blog.agentzh.org/#post-86>
"Client-side web site DIY" (Chinese)
<http://blog.agentzh.org/#post-80>
"OpenResty 平台相关资料" (Chinese)
<http://www.eeeeworks.org/#post-6>
CAVEATS
This library is still in the beta phase and the API is still in flux.
We're just following the "release early, releaes often" guideline. So
please check back often ;)
INSTALLATION
Please see OpenResty::Spec::Install for details :)
SOURCE TREE STRUCTURE
bin/
contains some command-line utilities, among which the openresty is
the most important one.
lib/
contains all the server code, mostly Perl.
haskell/
contains the RestyScript compiler for OpenResty written in Haskell.
Support for both OpenResty Views and Actions is provided.
See haskell/README for more details.
font/
contains the font file (*.ttf) for captcha generation.
etc/
contains the config files, openresty.conf and site_openresty.conf.
The latter one takes precedence over the former.
grammar/
contains Parse::Yapp grammar files for the old OpenResty View (or
minisql) compiler.
t/ contains the test suite.
demo/
contains a bunch of OpenResty demo apps.
inc/
generated by Module::Install for CPAN building system.
PERFORMANCE
OpenResty takes runtime performance very seriously because we have to
run it on our not-so-good servers and support lots of Yahoo! China's
online products with very heavy traffic.
OpenResty prefers modules with XS over pure Perl ones and uses cache
aggressively. It's also in favor of source-filter based solutions
provided by Filter::QuasiQuote to reduce the length of subroutine
calling chains and the number of indirections. Finally, the restyscript
compiler is also written in carefully optimized Haskell code to maximize
speed.
The benchmark results for OpenResty 0.5.3's test suite on a PentiumIV
3.0GHz machine is given below:
in-process frontend + PgMocked backend
DELETE: 4 ms (157 trials)
POST: 23 ms (493 trials)
PUT: 5 ms (132 trials)
GET: 4 ms (648 trials)
lighttpd fastcgi frontend + local Pg backend
DELETE: 29 ms (193 trials)
POST: 30 ms (815 trials)
PUT: 11 ms (138 trials)
GET: 9 ms (763 trials)
lighttpd fastcgi frontend + remote PgFarm backend
DELETE: 99 ms (193 trials)
POST: 98 ms (815 trials)
PUT: 41 ms (138 trials)
GET: 24 ms (763 trials)
SOURCE CONTROL
For the very latest version of this module, check out the source from
the Git repos below:
<http://github.com/agentzh/openresty/tree/master>
There is anonymous access to all. If you'd like a commit bit, please let
us know. :)
Mailing list
Subscribe to the "openresty" Google Group here:
L<http://groups.google.com/group/openresty>
Project Roadmap
Below is a list of currently planned release milestones (but it's also
supposed to change as we go):
0.5.x (Where we are)
Action API and an enhanced version of the Model API.
0.6.x
Migrate the View handler to the same style and implementation of the
Action handler, i.e., using explicit parameter list and taking
advantage of the Haskell version of the restyscript compiler.
Compiling view definition to native PostgreSQL functions is also
supposed to realize in this series.
0.7.x
Attachment API, which supports binary file uploading and
downloading.
0.8.x
Mail API, which introduces builtin Models for email sentbox and
inbox based on third-party POP3/STMP servers.
It will also allow actions to be triggered and/or confirmed by
emails.
0.9.x
Prophet/Git integration.
Please don't hesitate to tell us what you love to see in future releases
of OpenResty ;)
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>.
AUTHORS
Yichun Zhang (agentzh) "<agentzh at yahoo dot cn>"
Xunxin Wan (万珣新) "<wanxunxin at gmail dot com >"
chaoslawful (王晓哲) "<chaoslawful at gmail dot com>"
Lei Yonghua (leiyh)
Laser Henry (laser) "<laserhenry at gmail dot com>"
Yu Ting (yuting) "<yuting at yahoo dot cn>"
For a complete list of the contributors, please see
<http://svn.openfoundry.org/openapi/trunk/AUTHORS>.
License and Copyright
OpenResty is licensed under the BSD License:
Copyright (c) 2007-2008, Yahoo! China EEEE Works, Alibaba Inc. All
rights reserved.
Copyright (c) 2007-2008, Yichun Zhang (agentzh). All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Yahoo! China EEEE Works, Alibaba Inc. nor
the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER
OR CONTRIBUTORS 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.
SEE ALSO
OpenResty::Spec::Overview, openresty, OpenResty::Spec::REST_cn,
OpenResty::CheatSheet, WWW::OpenResty, WWW::OpenResty::Simple.