webmcp

changeset 278:b5d0c0ab3ce2

Updated documentation; Switched version string to "2.0.0"
author jbe
date Sat Mar 21 18:40:44 2015 +0100 (2015-03-21)
parents 2ddbb44680f7
children 680777af0293
files Makefile doc/apache.sample.conf doc/autodoc-footer.htmlpart doc/autodoc-header.htmlpart doc/lighttpd.sample.conf framework/bin/mcp.lua
line diff
     1.1 --- a/Makefile	Sat Mar 21 17:24:27 2015 +0100
     1.2 +++ b/Makefile	Sat Mar 21 18:40:44 2015 +0100
     1.3 @@ -9,7 +9,7 @@
     1.4  
     1.5  documentation::
     1.6  	rm -f doc/autodoc.tmp
     1.7 -	$(LUA_BIN) framework/bin/autodoc.lua framework/cgi-bin/ framework/env/ libraries/ > doc/autodoc.tmp
     1.8 +	$(LUA_BIN) framework/bin/autodoc.lua framework/env/ libraries/ > doc/autodoc.tmp
     1.9  	cat doc/autodoc-header.htmlpart doc/autodoc.tmp doc/autodoc-footer.htmlpart > doc/autodoc.html
    1.10  	rm -f doc/autodoc.tmp
    1.11  
     2.1 --- a/doc/apache.sample.conf	Sat Mar 21 17:24:27 2015 +0100
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,29 +0,0 @@
     2.4 -# Apache modules cgi_module, env, rewrite and alias must be loaded before
     2.5 -# Take a look in your main apache configuration!
     2.6 -
     2.7 -RewriteEngine on
     2.8 -# do not rewrite static URLs
     2.9 -RewriteRule ^/webmcp-demo/static/(.*)$ /webmcp-demo/static/$1
    2.10 -# dynamic URLs
    2.11 -RewriteRule ^/webmcp-demo/([^\?]*)(\?(.*))?$ /webmcp-demo/webmcp-wrapper.lua?_webmcp_path=$1&$3
    2.12 -
    2.13 -# Directly serve static files
    2.14 -Alias /webmcp-demo/static /__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__/static
    2.15 -
    2.16 -# Connect extarnal path to the webmcp cgi interface
    2.17 -ScriptAlias /webmcp-demo/ /__INSERT_LOCAL_FILE_PATH_TO_WEBMCP_FRAMEWORK_HERE__/cgi-bin/
    2.18 -
    2.19 -# Allow CGI execution for the webmcp CGI interface
    2.20 -<Directory "/__INSERT_LOCAL_FILE_PATH_TO_WEBMCP_FRAMEWORK_HERE__/cgi-bin">
    2.21 -    AllowOverride None
    2.22 -    Options ExecCGI -MultiViews +SymLinksIfOwnerMatch
    2.23 -    Order allow,deny
    2.24 -    Allow from all
    2.25 -</Directory>
    2.26 -
    2.27 -# Configure environment for demo application    
    2.28 -<Location /webmcp-demo>
    2.29 -    SetEnv WEBMCP_APP_BASEPATH '/__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__'
    2.30 -    SetEnv WEBMCP_CONFIG_NAME 'demo'
    2.31 -</Location>
    2.32 -
     3.1 --- a/doc/autodoc-footer.htmlpart	Sat Mar 21 17:24:27 2015 +0100
     3.2 +++ b/doc/autodoc-footer.htmlpart	Sat Mar 21 18:40:44 2015 +0100
     3.3 @@ -1,7 +1,7 @@
     3.4      </ul>
     3.5      <hr style="margin-top: 3em;"/>
     3.6      <p style="text-align: right; font-style: italic;">
     3.7 -      Copyright (c) 2009-2010 Public Software Group e. V., Berlin
     3.8 +      Copyright (c) 2009-2015 Public Software Group e. V., Berlin
     3.9      </p>
    3.10    </body>
    3.11  </html>
     4.1 --- a/doc/autodoc-header.htmlpart	Sat Mar 21 17:24:27 2015 +0100
     4.2 +++ b/doc/autodoc-header.htmlpart	Sat Mar 21 18:40:44 2015 +0100
     4.3 @@ -55,20 +55,63 @@
     4.4          color: #505050;
     4.5        }
     4.6      </style>
     4.7 -    <title>WebMCP 1.2.6 Documentation</title>
     4.8 +    <title>WebMCP 2.0.0 Documentation</title>
     4.9    </head>
    4.10    <body>
    4.11 -    <h1>WebMCP 1.2.6 Documentation</h1>
    4.12 +    <h1>WebMCP 2.0.0 Documentation</h1>
    4.13      <p>
    4.14 -      WebMCP is a completely new web development framework, and has not been extensively tested yet. The API might change at any time, but in future releases there will be a list of all changes, which break downward compatibility.
    4.15 +      WebMCP is a web development framework based on the Lua programming language (read more about Lua <a href="http://www.lua.org/about.html">here</a>).
    4.16      </p>
    4.17      <h2>Requirements</h2>
    4.18      <p>
    4.19 -      WebMCP has been developed on Linux and FreeBSD. Using it with Mac&nbsp;OS&nbsp;X is completely untested; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the programming language <a href="http://www.lua.org/">Lua</a> version 5.1, <a href="http://www.postgresql.org/">PostgreSQL</a> version 8.2 or higher, a C compiler, and a Webserver like Lighttpd or Apache.
    4.20 +      WebMCP has been developed on Linux and FreeBSD. Using it with Mac&nbsp;OS&nbsp;X is untested as of yet; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the <a href="http://www.lua.org/">programming language Lua</a> version 5.3, the <a href="http://www.public-software-group.org/moonbridge">Moonbridge Network Server for Lua Applications</a> version 0.4.0 or higher, <a href="http://www.postgresql.org/">PostgreSQL</a> version 8.2 or higher, and a C compiler.
    4.21      </p>
    4.22      <h2>Installation</h2>
    4.23      <p>
    4.24 -      After downloading the tar.gz package, unpack it, enter the unpacked directory and type <tt>make</tt>. If you use Mac OS X or if you experience problems during compilation, you need to edit the <tt>Makefile.options</tt> file prior to compilation. The framework itself will be available in the <tt>framework/</tt> directory, while a demo application is available in the <tt>demo-app/</tt> directory. The <tt>framework.precompiled/</tt> and <tt>demo-app.precompiled/</tt> directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with <tt>cp -L</tt> to follow links) to any other place you like. Use the files <tt>doc/lighttpd.sample.conf</tt> or <tt>doc/apache.sample.conf</tt> to setup your webserver appropriatly. Don't forget to setup a database, and make the <tt>tmp/</tt> directory of the application writable for the web server process. Good luck and have fun!
    4.25 +      After downloading the tar.gz package, unpack it, enter the unpacked directory and type <tt>make</tt>. If you use Mac OS X or if you experience problems during compilation, you need to edit the <tt>Makefile.options</tt> file prior to compilation. The framework itself will be available in the <tt>framework/</tt> directory, while a demo application is available in the <tt>demo-app/</tt> directory. The <tt>framework.precompiled/</tt> and <tt>demo-app.precompiled/</tt> directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with <tt>cp -L</tt> to follow links) to any other place you like. Don't forget to setup a database, and make the <tt>tmp/</tt> directory of the application writable for the web server process. Good luck and have fun!
    4.26 +    </p>
    4.27 +    <h2>Configuration, pre-fork and post-fork initializers</h2>
    4.28 +    <p>
    4.29 +      The Moonbridge Network Server creates forks (i.e. clones) of the application server process in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. The application's configuration files as well as its pre-fork initializers are executed before forking. The application's post-fork initializers are executed after forking. In particular, any libraries that open file or network handles during initialization must not be loaded before the server process is forked. Opening database connections must be performed after forking as well. Execution order is as follows:
    4.30 +    </p>
    4.31 +    <ol>
    4.32 +      <li>
    4.33 +        Loading all WebMCP libraries except the "multirand" library (multirand opens /dev/urandom and thus must not be loaded prior to forking)
    4.34 +      </li>
    4.35 +      <li>
    4.36 +        Executing the selected configuration file: <tt>config/</tt><i>configuration_name</i><tt>.lua</tt>
    4.37 +      </li>
    4.38 +      <li>
    4.39 +        Executing all pre-fork initializers (both those in the <tt>app/_prefork/</tt> and those in the <tt>app/</tt><i>application_name</i><tt>/_prefork/</tt> directory) until call of <tt>execute.inner()</tt> within each initializer
    4.40 +      </li>
    4.41 +      <li>
    4.42 +        The Moonbridge Network Server forks the process (i.e. cloning the whole Lua machine)<br />
    4.43 +        <span style="color: red">Note: no file handles or network connections must be opened prior to this point!</span>
    4.44 +      </li>
    4.45 +      <li>
    4.46 +        Executing all post-fork initializers (both those in the <tt>app/_postfork/</tt> and those in the <tt>app/</tt><i>application_name</i><tt>/_postfork/</tt> directory) until call of <tt>execute.inner()</tt> within each initializer
    4.47 +      </li>
    4.48 +      <li>
    4.49 +        For each request:
    4.50 +        <ul>
    4.51 +          <li>
    4.52 +            Execution of all applicable filters until call of <tt>execute.inner()</tt> within each filter
    4.53 +          </li>
    4.54 +          <li>
    4.55 +            Handling of the request by calling the appropriate view or action
    4.56 +          </li>
    4.57 +          <li>
    4.58 +            Resuming execution of all filters in reverse order from that position where <tt>execute.inner()</tt> had been called
    4.59 +          </li>
    4.60 +        </ul>
    4.61 +      </li>
    4.62 +      <li>
    4.63 +        Resuming execution of all post-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called
    4.64 +      </li>
    4.65 +      <li>
    4.66 +        Resuming execution of all pre-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called
    4.67 +      </li>
    4.68 +    </ol>
    4.69      </p>
    4.70      <h2>Using the atom library</h2>
    4.71      <p>
    4.72 @@ -97,23 +140,28 @@
    4.73      </p>
    4.74      <h2>Using the Object-Relational Mapper &ldquo;mondelefant&rdquo;</h2>
    4.75      <p>
    4.76 -      The library &ldquo;mondelefant&rdquo; shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). Opening a connection to a database is usually done in a config file in the following way:
    4.77 +      The library &ldquo;mondelefant&rdquo; shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). The database connection is usually configured in the config file (e.g. in <tt>config/devel.lua</tt>):
    4.78 +    </p>
    4.79 +    <pre>
    4.80 +config.db = { engine="postgresql", dbname="webmcp_demo" }
    4.81 +config.db_trace = true</pre>
    4.82 +    <p>
    4.83 +      In addition to configuring the database, it must be opened within a post-fork initializer (e.g. in <tt>app/_postfork/01_database.lua</tt>):
    4.84      </p>
    4.85      <pre>
    4.86 -db = assert( mondelefant.connect{ engine='postgresql', dbname='webmcp_demo' } )
    4.87 -at_exit(function() 
    4.88 -  db:close()
    4.89 -end)
    4.90 +_G.db = assert(mondelefant.connect(config.db))
    4.91  function mondelefant.class_prototype:get_db_conn() return db end
    4.92  
    4.93 -function db:sql_tracer(command)
    4.94 -  return function(error_info)
    4.95 -    local error_info = error_info or {}
    4.96 -    trace.sql{ command = command, error_position = error_info.position }
    4.97 +if config.db_trace then
    4.98 +  function db:sql_tracer(command)
    4.99 +    return function(error_info)
   4.100 +      local error_info = error_info or {}
   4.101 +      trace.sql{ command = command, error_position = error_info.position }
   4.102 +    end
   4.103    end
   4.104  end</pre>
   4.105      <p>
   4.106 -      Overwriting the <tt>sql_tracer</tt> method of the database handle is optional, but helpful for debugging. The parameters for <tt>mondelefant.connect</tt> are directly passed to PostgreSQL's client library libpq. See <a href="http://www.postgresql.org/docs/8.4/interactive/libpq-connect.html">PostgreSQL's documentation on PQconnect</a> for information about supported parameters.
   4.107 +      Overwriting the <tt>sql_tracer</tt> method of the database handle is optional, but helpful for debugging. The parameters for <tt>mondelefant.connect</tt> are directly passed to PostgreSQL's client library libpq. See <a href="http://www.postgresql.org/docs/9.4/static/libpq-connect.html">PostgreSQL's documentation on PQconnect</a> for information about supported parameters.
   4.108      </p>
   4.109      <p>
   4.110        To define a model to be used within a WebMCP application, create a file named with the name of the model and <tt>.lua</tt> as extension in the <tt>model/</tt> directory of your application. The most basic definition of a model (named &ldquo;movie&rdquo; in this example) is:
   4.111 @@ -165,15 +213,53 @@
   4.112              <tt>app/</tt>
   4.113              <ul>
   4.114                <li>
   4.115 +                <tt>_prefork/</tt>
   4.116 +                <ul>
   4.117 +                  <li>
   4.118 +                    <tt>10_first_prefork_initializer.lua</tt>
   4.119 +                  </li>
   4.120 +                  <li>
   4.121 +                    <tt>30_third_prefork_initializer.lua</tt>
   4.122 +                  </li>
   4.123 +                </ul>
   4.124 +              </li>
   4.125 +              <li>
   4.126 +                <tt>_postfork/</tt>
   4.127 +                <ul>
   4.128 +                  <li>
   4.129 +                    <tt>01_first_postfork_initializer.lua</tt>
   4.130 +                  </li>
   4.131 +                  <li>
   4.132 +                    <tt>03_third_postfork_initializer.lua</tt>
   4.133 +                  </li>
   4.134 +                </ul>
   4.135 +              </li>
   4.136 +              <li>
   4.137                  <tt>main/</tt>
   4.138                  <ul>
   4.139                    <li>
   4.140 +                    <tt>_prefork/</tt>
   4.141 +                    <ul>
   4.142 +                      <li>
   4.143 +                        <tt>20_second_prefork_initializer.lua</tt>
   4.144 +                      </li>
   4.145 +                    </ul>
   4.146 +                  </li>
   4.147 +                  <li>
   4.148 +                    <tt>_postfork/</tt>
   4.149 +                    <ul>
   4.150 +                      <li>
   4.151 +                        <tt>02_second_postfork_initializer.lua</tt>
   4.152 +                      </li>
   4.153 +                    </ul>
   4.154 +                  </li>
   4.155 +                  <li>
   4.156                      <tt>_filter/</tt>
   4.157                      <ul>
   4.158                        <li>
   4.159                          <tt>10_first_filter.lua</tt>
   4.160 +                      </li>
   4.161                        <li>
   4.162 -                      </li>
   4.163                          <tt>30_third_filter.lua</tt>
   4.164                        </li>
   4.165                        <li>&hellip;</li>
   4.166 @@ -302,5 +388,23 @@
   4.167          </ul>
   4.168        </li>
   4.169      </ul>
   4.170 +    <h2>Starting your application</h2>
   4.171 +    <p>
   4.172 +      Ensure that the <tt>moonbridge</tt> binary is within your system's search path and that the <tt>moonbridge_http.lua</tt> file is included in the LUA_PATH or linked into the framework's <tt>lib/</tt> directory (alternatively the MOONBR_LUA_PATH option might be set accordingly at compile-time of the Moonbridge Network Server). To start an application, call the <tt>mcp.lua</tt> executable (found in <tt>framework/bin/mcp.lua</tt>) with the following arguments:
   4.173 +    </p>
   4.174 +    <ol>
   4.175 +      <li>
   4.176 +        Path of the WebMCP framework directory, e.g. <tt>./framework</tt>
   4.177 +      </li>
   4.178 +      <li>
   4.179 +        Path of your application's directory, e.g. <tt>./demo-app</tt>
   4.180 +      </li>
   4.181 +      <li>
   4.182 +        Name of your applicaiton (usually <tt>main</tt>)
   4.183 +      </li>
   4.184 +      <li>
   4.185 +        Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)
   4.186 +      </li>
   4.187 +    </ol>
   4.188      <h2>Automatically generated reference for the WebMCP environment</h2>
   4.189      <ul>
     5.1 --- a/doc/lighttpd.sample.conf	Sat Mar 21 17:24:27 2015 +0100
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,44 +0,0 @@
     5.4 -# Lighttpd modules needed by WebMCP
     5.5 -server.modules += (
     5.6 -  "mod_cgi",
     5.7 -  "mod_alias",
     5.8 -  "mod_setenv",
     5.9 -  "mod_rewrite",
    5.10 -  "mod_redirect",
    5.11 - )
    5.12 -
    5.13 -# Enable CGI-Execution of *.lua files through lua binary
    5.14 -cgi.assign += ( ".lua" => "/__INSERT_LOCAL_FILE_PATH_TO_LUA_BINARY_HERE__/lua" )
    5.15 -
    5.16 -# Connect external URLs to server static files and the webmcp cgi interface
    5.17 -alias.url += (
    5.18 -  "/webmcp-demo/static/" => "/__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__/static/",
    5.19 -  "/webmcp-demo/"        => "/__INSERT_LOCAL_FILE_PATH_TO_WEBMCP_FRAMEWORK_HERE__/cgi-bin/" )
    5.20 -
    5.21 -# Configure environment for demo application    
    5.22 -$HTTP["url"] =~ "^/webmcp-demo/" {
    5.23 -  setenv.add-environment += (
    5.24 -    "WEBMCP_APP_BASEPATH" => "/__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__",
    5.25 -    "WEBMCP_CONFIG_NAME"  => "demo")
    5.26 -}
    5.27 -
    5.28 -# URL beautification
    5.29 -url.rewrite-once += (
    5.30 -
    5.31 -  # do not rewrite static URLs
    5.32 -      "^/webmcp-demo/static/(.*)$" =>
    5.33 -      "/webmcp-demo/static/$1",
    5.34 -
    5.35 -  # dynamic URLs
    5.36 -      "^/webmcp-demo/([^\?]*)(\?(.*))?$" =>
    5.37 -      "/webmcp-demo/webmcp-wrapper.lua?_webmcp_path=$1&$3",
    5.38 -
    5.39 -)
    5.40 -
    5.41 -# Redirects for URLs without trailing slashes
    5.42 -url.redirect += (
    5.43 -  # base URL without trailing slash
    5.44 -      "^/webmcp-demo$" => "/webmcp-demo/",
    5.45 -  # module base URL without trailing slash
    5.46 -      "^/webmcp-demo/([^/\?]+)$" => "/webmcp-demo/$1/",
    5.47 -)
     6.1 --- a/framework/bin/mcp.lua	Sat Mar 21 17:24:27 2015 +0100
     6.2 +++ b/framework/bin/mcp.lua	Sat Mar 21 18:40:44 2015 +0100
     6.3 @@ -1,6 +1,6 @@
     6.4  #!/usr/bin/env moonbridge
     6.5  
     6.6 -WEBMCP_VERSION = "2.0.0_devel"
     6.7 +WEBMCP_VERSION = "2.0.0"
     6.8  
     6.9  -- allow control of global environment
    6.10  local _G = _G

Impressum / About Us