-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
186 lines (133 loc) · 7.33 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
In yet another in a long string of rapid-fire ideas turned into alpha
quality code, I'd like to annouce the availability of the Pike
ScriptRunner. ScriptRunner is a FastCGI application that will
(hopefully) run under pretty much any web server that supports FastCGI.
The ScriptRunner allow you to run pike scripts under non-pike based web
servers. Because ScriptRunner uses FastCGI, 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 the (more likely) attachment to Apache. 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.
Requirements:
Pike 7.6+
libfastcgi (available from http://www.fastcgi.com)
Public.Web.FastCGI (available from
http://www.siriushosting.com/pike/fastcgi.html)
Features:
- Multi-threaded request handling
- Session persistence
- Persistent interpreter
- Compiled object caching
- Incoming requests are parsed and passed to you in a request id object.
- Handles FCGI processing for you. Just return a string or control mapping
from your parse() method.
Installation:
Please visit the ScriptRunner page for more updated information:
http://www.gotpike.org/PikeWiki/index.pike?page=PikeApps/Pike+ScriptRunner
Basic installation instructions are located in the file INSTALL.
Apache users: see the file INSTALL.Apache for information on configuring
Apache support for FastCGI.
Get the snapshot tarball here:
http://buoy.riverweb.com:8080/viewrep/cvs/scriptrunner
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:
http://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
http://www.mysite.com/some/other/path.pike
to
http://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 .pike
Action scriptrunner-pike-script /path/to/ScriptRunner.fcgi
In the long run, this may be a simpler option.
Some example scripts are included to give you a head start.
Writing Pike Scripts:
First of all, you should know how to write code in the Pike language. It's
pretty easy, and if you're accustomed to C-like languages, such as C or
Java, you should be able to pick things up in a few minutes.
A pike script must impliment the following method:
string|mapping parse(RequestID request_id);
request_id is an object that contains the request information, all broken
down into the most important components. Accessing the scriptrunner
application without providing a script file will give you an example of
what's contained in the RequestID object.
Some important members of a RequestID object:
variables: a mapping containing key-value pairs for all passed query and
POST variables. ScriptRunner does not differentiate between GET and POST
variables.
cookies: a mapping containing key-value pairs for all cookies provided to
the server during the request.
query: the contents of the request string following the ?
method: the HTTP method sent by the client.
client: an array containing elements of the client agent being used.
pragma: a multiset containing any pragma keys sent by the client agent.
the most common of these is "no-cache".
prot: the http protocol and version, for example: HTTP/1.0.
referrer: an array containing the referrer.
remoteaddr: the client's ip address
remotehost: the client's remote hostname, if available.
misc: a mapping containing miscellaneous information about the request.
misc->session_variables: if set to use sessions, your script or psp page
will have a mapping here that you can add to and which will be maintained
across requests. Currently, this can not contain programs or objects.
misc->session_id: if set to use sessions, this will be a string containing
the current session identifier.
Your parse() function can run any pike code you'd like, and when you're
done, it should return either a string containing the HTML content to
return to the browser, or a "control" mapping. A control mapping is a
mapping that contains certain indices that control the response returned
to the browser. You'd want to return a mapping if you need to alter the
content type of the result, or if you want to add special headers or
change the status code. example2.pike gives you an example of a control
mapping used to perform a HTTP redirect. Future releases of ScriptRunner
will provide convenience functions that will generate appropriate control
mappings for you. Until then, Here are the contents (and default falues):
([
/* the result code to return, 200 is "OK" */
"error" : 200
/* the mime content type to return */
"type" : "content/html"
/* a string or Stdio.File object containing the data to return. If a
File object, the data will be read() from the object. Not required,
strictly speaking, but it is normally important to provide. */
"data" : UNDEFINED
/* a mapping containing response headers to provide */
"_headers" : UNDEFINED
])
Do note that the contents of this mapping may change once convenience
functions arrive. If you find yourself performing a large number of string
concatenations to create the result string, you may want to consider using
String.Buffer, which can improve the performance of your application in
these situations. See the Pike module reference for more information on
String.Buffer.
Upon successful compilation of your script, it will be instantiated into
an object, so you can provide create() and destroy() methods to control
startup and shutdown of services required by parse(). Note that upon
compilation, scripts are cached. Scripts can currently be reloaded by
sending the Pragma: no-cache header (by doing a "super reload" using
mozilla based browsers). Do not count on destroy() to be called
immediately upon destruction, as there may be a delay between the script
being recompiled and garbage collection, which forces destroy() to be
called.
In the event of a compilation failure, the error will be displayed to the
client and written to a log file. Compilation retries will occurr on
subsequent requests. In the event of an uncaught error exception, an
error and stacktrace will be returned to the browser, as well as written
to the log file.
Comments, Feedback and Participation:
I welcome all of these, especially if you're interested in helping to
debug and enhance the code. Contact me if you'd like to help out.