PikeApps/Pike ScriptRunner

Because ScriptRunner uses http://www.fastcgi.com or SCGI, its performance should be close to embedded language solutions like mod_perl, but with a lot less worries about security and overflows. With ScriptRunner you can introduce all of your friends to Pike without forcing them to suffer bad performance or (more likely) give up their attachment to Apache or other web servers. In addition, ScriptRunner does a lot of the unpleasant work of parsing incoming requests, allowing you to get right to the task of writing your code.

Right now, it's pretty early on in its development, so there are a lot of niceties present in Roxen or Caudium that aren't available, and it's not terribly well tested, so it could have some nasty bugs. Enough raw functionality is available to be highly useful; hopefully there will be interest in improving things in this area. ScriptRunner contains code written by others over the years; this is really more of a gathering of snippets into something more readily useful to others.

Apache users: see the file INSTALL.Apache in the source distribution for information on configuring Apache support for FastCGI.

4. Edit the scriptrunner application, specify an optional log file (recommended), and verify any settings you'd like to change.

5. Add a redirect to convert all requests to (*.pike) to /path/to/scriptrunner.fcgi($1) (actual syntax will vary based on the redirector you're using.

For example, if I've installed ScriptRunner so that the ScriptRunner.fcgi is called by the following request:

www.mysite.com/path/to/ScriptRunner.fcgi

and I put a pike script in /some/other/path.pike on my website, I need my redirect to internally change

www.mysite.com/some/other/path.pike

www.mysite.com/path/to/ScriptRunner.fcgi/some/other/path.pike

This is a common technique used by PHP and other languages. Alternately, you could use mod_actions to do the same thing:

   AddHandler scriptrunner-pike-script asis 
   AddHandler scriptrunner-pike-script .pike
   AddHandler scriptrunner-pike-script .psp
   Action scriptrunner-pike-script /path/to/ScriptRunner.fcgi

<IfModule fcgid_module>    
  AddHandler fcgid-script .fcgi
</IfModule><IfModule actions_module>
  AddHandler scriptrunner-pike-script .pike
  Action scriptrunner-pike-script /ScriptRunner.fcgi
  AddHandler scriptrunner-pike-server-page .psp   Action scriptrunner-pike-server-page /ScriptRunner.fcgi
</IfModule>

Lighttpd comes with fcgi and scgi support out of the box, so if you've got a working ScriptRunner.fcgi/scgi, you can enable support by adding the following to your lighttpd.conf:

scgi.server = ( ".pike" => (( 
  "host" => "127.0.0.1",
  "port" => 9999
 )) )

It appears that the scgi module doesn't auto-start the process, so you'll need to start ScriptRunner.scgi with the appropriate --port= option to get things working, but it should work right out of the gate.

fastcgi.server = (".pike" =>
                   ( "localhost" =>
                    (
                     "socket" => "/tmp/scriptrunner.socket",
                     "check-local" => "disable",
                     "bin-path" => "/path/to/scriptrunner/ScriptRunner.fcgi",
                     "min-procs" => 1,
                     "max-procs" => 5,
                     "idle-timeout" => 30
                    )
                   )
                  )

ScriptRunner can be run in either single or multithreaded mode. Basically, this means that you can either have one thread processing all requests, or have a set of threads processing requests concurrently. Note that multithreaded operation doesn't necessarily mean that your scripts will run faster. In fact, single threaded operation tends to run about 4-5% faster on simple requests. You may find multithreading useful when performing large numbers of operations such as Image manipulations or SQL transactions, which are typically performed in C libraries, which often allow concurrent operations.

To enable (or disable) threaded operation, simply uncomment (or comment) the line in ScriptRunner.fcgi that looks like this:

#define RUN_THREADED

And restart ScriptRunner.fcgi (which may involve restarting your web server software). You can verify that ScriptRunner is running in single or multithreaded mode by making multiple requests to ScriptRunner.fcgi without a file argument. The first line following the version will indicate the thread handling the request. If the thread changes, you're running multiple handler threads; if it stays zero (0) across multiple requests, you're in singlethreaded mode.

Several users have reported difficulties running ScriptRunner under Ubuntu. The problem centers around Ubuntu ignoring options on the header line, such as:

#!/usr/local/bin/pike -M/usr/local/scriptrunner/lib

Two simple workarounds include writing a wrapper script that simply executes ScriptRunner with the appropriate options, or moving the contents of the scriptrunner/lib directory to your system's Pike modules path.

ScriptRunner has been tested to work with the following web servers in the following modes (note that just because the combination you'd like to use isn't listed, doesn't mean it won't work):

Apache 1.3/2.0 runs happily in FastCGI mode. Note: there are some "defects" in the way that mod_scgi works on Apache that may cause your scripts to behave improperly. We're working with the author of mod_scgi to work out a fix.

lighttpd 1.4.x runs happily in both FastCGI and SCGI mode, though we weren't smart enough to figure out how to get lighttpd to spawn ScriptRunner automatically using either mode. Pre-starting ScriptRunner seemed to work just fine, though.

Caudium 1.4 will run ScriptRunner in FastCGI mode using either the FastCGI or FastUniscript modules.

We'd be pleased to hear of any success stories (as well as configurations) that you've had success (or trouble) with. Drop the author a note at hwww3 at riverweb dot com.

Pike scripts look a lot like C or Java, but the first thing you'll notice is that they're far less verbose. One of the nice things about Pike is that a lot of powerful language constructs and methods are available to you out of the box. For example, the following script will render the contents of the form variable "input" as text on a PNG image:

mapping parse(object id)
{
  // note that all of the most commonly used pieces of the request are
  // assembled in the request id object. 
  if(!id->variables->input)
    id->variables->input = "Default Text";   // the last argument is set to 1 to ensure we get a font back, even
   // if we don't have the one we're looking for.
  object fnt = Image.Fonts.load_font("Times New Roman", 72, 0, 1);
  object img = fnt->write(id->variables->input);
  string output = Image.PNG.encode(img);
  return (["data": output, "type": "image/png"]);
}

The following example demonstrates Pike's database-independent SQL API. In this example, we're running a database query and returning the results as a table. Also note that we've added some code to speed processing: we keep the database connection open between requests.

object sql;
string sql_url = "mysql://user:pass@localhost/mydb";
string parse(object id)
{
  if(!sql)
    sql = connect_sql(sql_url);
  // note that we use 'sprintf' like features here. the replacement variables
  // get automatically quoted as appropriate for the underlying database.
  // we're also using the 'simple query' interface that returns the result
  // as an array of mappings (hashes)
  array sql_result = sql->query("SELECT firstname, lastname, phone FROM addresses WHERE lastname like %s", "Smith%");
  if(!sizeof(sql_result))
    return "sorry, there were no entries.";
  String.Buffer r = String.Buffer();
  // In addition to standard object oriented method calls, 
  // Pike supports operator overloading, which allows objects to
  // appear as though they were simple datatypes. This allows us to
  // start with strings, and very simply replace the more efficient
  // string buffer object, with only 2 changes to our code
  r += "<table>";
  // let's loop through the result set
  foreach(sql_result; int index; mapping row)
    r += sprintf("<tr><td>%s, %s</td><td>%s</td></tr>", 
                 row->lastname, row->firstname, row->phone);
  r+="</table>";
  // we could have just as easily cast the buffer to a string.
  return r->get();
}
object connect_sql(string url)
{
  object s;
  if(catch(s = Sql.Sql(url)))
    throw(Error.Generic("Unable to connect to the database.&#110;"));
  return s;
}

Some example scripts (they all start with test) are included to give you a head start. More extensive documentation is available in the source distribution.

As of version 0.3, ScriptRunner supports session state persistence. Currently the session storage engine uses a hash directory and serialization files, which means that it's not optimized for performance. Additional engines are welcome, some potential options include: RAM, SQL and Memcache.

To use sessions in your Pike Script, simply add an integer "__participates_in_session" with a value of 1. See the class ScriptRunner.SRPikeScript for details. If this value is set, ScriptRunner will create a session cookie (if necessary), and retrieve any previously set session variables. The session information can be found within the following mapping in your RequestID object:

request->misc->session_variables

request->misc->session_id

Simply place any data (no objects or programs yet, please!) you wish to persist into this mapping, and it will be saved between requests. Do note that the more data you place into this mapping, the slower your session will run, as it must be (currently serialized) and saved between requests.

Pike ScriptRunner is free software made available under the GPL/LGPL/MPL licenses. We're just getting started, so we're not totally organized yet. For the time being, send email to the Pike mailing list: pike at roxen dot com or to the author: bill at gotpike dot org.