Graal Forums - Grattpd: the world's best (GScript) web server

1. Description
I present to you Grattpd, the world's best GScript-powered webserver. Sporting cookies, POST/GET data, includes, and more, Grattpd is the only way to go if you're looking for a web server that does it all!

Grattpd enables you to run a web site from your Graal server. Combined with my FTP server, you've got your own web host!

The benefit of using Grattpd for your server's web site is that you can easily use data from the server itself, such as the current playercount or server news. It also makes it easy to integrate your web site with other functions of the server, such as a support center or message board.

Attached is a zip file with all of the scripts used, as well as a demo file (which shows how to use dynamic web pages) and the error page (which you can, of course, change). The instructions below will guide you through installation.

2. Installation

Download the attached ZIP file and extract it.
Create a class for each file in the "classes" folder and copy the script in there. Alternatively, you could upload all of the TXT files into the "scripts" folder of your server and restart the NPC-server.
Create a new database NPC with type "CONTROL". Place it in any level (preferably a level that won't be ever deleted). Name the NPC "WebServer", and copy and paste the code from "npcs/WebServer.txt", which was in the ZIP you extracted.
Give yourself and (npcserver) the following rights:

Quote:

rw webserver/public/*
rw webserver/public/*/*
rw webserver/public/*/*/*
rw webserver/priv/*
rw webserver/priv/*/*
rw webserver/priv/*/*/*

(feel free to expand these if you require more subdirectories)
In the ZIP file, upload "webserver/public/index.arc" to the corresponding folder on the server. Do the same for "webserver/priv/error.arc" and "webserver/priv/bad_browser.html".

Note: bad_browser.html is shown if the user is attempting to access the site via Internet Explorer 6. The site I was making for Era explodes under IE 6, so I decided simply to disable access, which is fairly common practice. You can remove this code (it's in http_clientsocket) if you'd prefer.
Try accessing the site. It will be at the server and port which echoed to RC earlier.

For example, if you saw

Quote:

HTTP: Bound to 50.23.136.183:44989, waiting for connections...

you want to go to http://50.23.136.183:44989/

If it's not working, you probably did something wrong. If you can't figure it out, feel free to ask a question in this thread.

Your web server should now be up and running. The section below will explain how to use the various features of the web server.

3. Usage
3.1 Static vs Dynamic
There are two types of content you will serve: static and dynamic. Static content does not change. Dynamic content does.

An example of static content on a typical web page would be images, spreadsheets, and JavaScript. An example of dynamic content could be the page itself, which may change based on a certain condition (for example, it might display the playercount or show the name of the logged-in user).

For static content, simply upload the file to webserver/public/ and it will be served as-is.

For dynamic content, I've chosen to use handler classes. The benefit of using classes for different pages is that you have total control over the page. My preferred method of using dynamic content is to have HTML in a file, and use a handler class for replacing keywords like <&LOGGED_IN_USER&> with the proper text. This is the only method which I will explain, although it is very easy to figure out how to do it another way by looking at the class http_handler_replace.

3.2 Dynamic Content
For must usage cases, each page will have its own handler class. If you open the example index.arc file I included, you will see the following:

HTML Code:

### http_handler_page_demo

<!doctype html>

<html>

        <head>

                <title>It works!</title>

        </head>

        

        <body>

                <h1>Hoorah!</h1>

                <p>Grattpd is working! There are currently <&PLAYERS&> players online!</p>

        </body>

</html>

The first line defines the handler that the page will use. I've arbitrarily named it a "shebang" for simplicity.

The shebang consists of three pounds, a space, and the name of the handler class. The code in this specific handler class looks like this:

PHP Code:


		
			
function onCreated() {

  this.join("http_handler_replace");

}



function onReady() {

  this.socket.sendStatus(200, "OK");

  this.socket.sendHeader("Content-Type: text/html");

  

  temp.replace = {

                   {"PLAYERS", allplayers.size()}

                 };

  

  this.replaceInfo(replace);

  this.sendData();

}

You can use this template for your own pages. It should be fairly obvious how to add additional parameters to be replaced.

Files ending in .arc are considered dynamic. Files with any other extension will be served as-is.

3.3 Restricted File Types
Unfortunately, the NPC-server can only interact with certain file types. This is why I am using "ARC" for dynamic content instead of something more semantic.

The following file types are known to work with the NPC-server (this is a very small list, I don't have the full one):

html
txt
arc
png
jpg
gif
gani
nw
db
css

The "js" extension, which is used for JavaScript source files, is not currently allowed. As a workaround, files whose names end with "_js.txt" will be sent with an application/javascript Content-type header. You could also embed JavaScript directly into your web pages.

3.4 Cookies
Cookies are small pieces of data which are stored by the web browser. They are used for logins, among other things. Grattpd supports cookies.

To send a cookie for the browser to store, use this command from the handler class:

PHP Code:


		
			
this.socket.sendCookie("username", "chris"); // var name, value

To access a cookie which you have previously set, use this command from the handler class:

PHP Code:


		
			
echo(this.socket.cookie.username);

Remember that cookies can be faked by the user, so always validate them. Don't trust a cookie like "logged_in" or "username" without verifying it with some token or hash you've also stored as a cookie.

It is important to keep in mind that cookies are user-submitted data, so if you're using them in conjunction with SQLite, you need to remember to escape them.

3.5 GET/POST data
GET data is data attached to the URL of a page. For example, the URL might look like http://example.com/?threadid=123&postsperpage=1.

POST data is data which you can't see in the URL. An example of it would be when you make a post on these forums. The content of your post is sent via POST.

To access this data, use the following from the handler class:

PHP Code:


		
			
echo(this.socket.data.get.value);

echo(this.socket.data.post.value);

You can find an explanation of GET and POST data here.

3.6 Includes
Includes allow you to include another file inside the current file. Grattpd supports this very well. You can include both static and dynamic files.

An example of a file which uses includes:

HTML Code:

### http_handler_page_home

<&INCLUDE priv/templates/main/header.arc &>

<h1>Welcome to Era!</h1>

<p>Enter Era and find yourself immersed in modern city life. Fight using assault rifles, shotguns, and more! This 2D adventure pits you against the ruthless gangs that run the streets of Graal.</p>



<&INCLUDE priv/templates/main/footer.arc &>

The value of includes should be immediately obvious. You can use includes by placing the following in any dynamic file:

HTML Code:

<&INCLUDE path/to/file &>

The path is relative to the web root. In most cases you will want to store your templates outside of the public web, so you will want to do something like "priv/templates/header.arc". This would load a file in "webserver/priv/templates/header.arc".

For includes to work, your handler class must call this.socket.addIncludes();. This is an example of a handler class which uses includes:

PHP Code:


		
			
function onCreated() {

  this.join("http_handler_replace");

}



function onReady() {

  this.socket.sendStatus(200, "OK");

  this.socket.sendHeader("Content-Type: text/html; charset=UTF-8");

  this.socket.selectedSection = "home";

  this.socket.pageTitle = "Era: Graal's most popular modern playerworld.";

  this.socket.pageTitleNoSuffix = true;

  

  this.socket.addIncludes();

  

  temp.replace = {

    {"test", "test2"}

  };

  

  this.replaceInfo(replace);

  this.sendData();

}

Post continued below

Edit by Skyld: Links approved.