Pliant HTTP server

The Pliant HTTP server is designed mainly for serving dynamic pages, but it can also be used as a classical HTTP server. It's key difference with other HTTP servers is that it introduces a new text file format, called .page. The .page file format can be learned in very few time, because it's not more complicated to write .page files than to write HTML pages using a text editor, but it scales incredibly better because .page files are true Pliant programs, so adding dynamic features is easy, is done using the very consistent Pliant syntax, and you get all Pliant language power (dynamic compiling, meta programming).

The performances of the Pliant HTTP server as a static pages server are probably not very high, and it's not a main goal to increase this because focusing on static pages only servers is stupid: most sites are network bandwild bounded, so the only interesting goals are getting more flexibility and reasonable security.
However, should your site be processor speed bounded, it's probably not due to static pages servicing but due to true dynamic pages servicing.
Now, if you really are a very special site that has so much bandwild that you get processor speed bounded, the best to do is probably to run two HTTP servers in a Linux box: the Linux kernel HTTP server will fast service the most frequently accessed static pages, and the Pliant HTTP server will give you the greatest flexibility on dynamic pages. Another even more powerfull alternative might be to use TUX (developped by the clever Ingo Molnar) as the kernel HTTP server.If you need such solutions, please keep in touch we me so that I can provide you advises on how to configure your server, and add improvements in order to increase Pliant HTTP server scalability based on real big sites experiments rather than abstract benchmark numbers.

The simplest way to start Pliant HTTP server is to type in the following command at the shell prompt:

pliant module /pliant/protocol/http/server.pli command 'http_server configure'

pliant module /pliant/protocol/http/server.pli command 'http_server port 8080 configure'

Use the second version if another HTTP server is running on your computer or if you are running Unix and don't have root rights.
If everything works fine, you should be prompted for the administrator id and password, then get a message:
HTTP server is running on TCP port 80.
or HTTP server is running on TCP port 8080.
and the program should not stop.
If the program stoped (you get back to the prompt), you probably have another HTTP server already running (you can get around that changing the port value), or your TCP/IP layer is not configured properly at operating system level. On a Unix system, you may also not be able to start the HTTP server on port 80 if you don't have 'root' rights.

Important: If you specifyed 'configure' option when starting the HTTP server, then, in your browser, you have to connect to the server using http://localhost/ or http://localhost:8080/ but not any other server name such as the real name of your computer since the access would be rejected unless you HTTP server is already fully configured.

Now, these are all options you may select when starting the HTTP server:
pliant module /pliant/protocol/http/server.pli command 'http_server configure simulate a_string name a_string port an_integer secured secured_port an_integer channel an_array_of_strings protocol_level a_string send_software_release_number a_boolean maximal_form_length an_integer log a_string'

If you want the HTTP server to start faster, you can use Pliant precompiling capabilities.
So, you'll simply enter something like:

pliant 'precompile /binary/http.dump module /pliant/protocol/http/server.pli module /pliant/protocol/http/style/default.style' module /pliant/protocol/http/server.pli command http_server

The new Pliant security mechanism for the HTTP server is based on an infinit number of rights. Each right is identifyed by a (case sensitive) string.
When the request is received, the HTTP will look in the users database and grant rights.

A not logged in client will be assigned to user 'anonymous'
Before sending the requested page to the client, the server will check that the user as 'read' right.

which means that he has the right specifyed in the 'Read' field of the area he is trying to access.
The dynamic page can also test other rights ('allowed'

method) and so decide to hide some parts of the page and so on, or simply reject the user request if the specifyed right is not granted ('requires'

method).

A .page file is something that will be executed by the Pliant server, so if you let a user upload a .page (or upload something, then rename it to .page), then it can be a torjan horse.

Right	Meaning
`administrator`	A user which is granted `adminstrator` right is granted all other rights.
`read`	This is a special right assigned to the user when he has the right specifyed in the 'Read' field of the area of the site the request applies to. You should never use this in the web sites and users configuration tables. It's used internaly by the Pliant HTTP server.
`write`	This is a special right assigned to the user when he has the right specifyed in the 'Write' field of the area of the site the request applies to.You should never use this in the web sites and users configuration tables. You can use it in a .page dynamic page in order to test if the use is allowed to "write" in the specifyed area. What "write" means is left free to your application. Most of the time it should mean that the user is allowed to do some kind of upload or patch upload, but you have to keep in mind that if a user is allowed to upload a .page file that will not be displayed using ultrasafe style, then he is allowed to upload a torjan horse.

If you want to use secured access to the web site you have to:

Define the web site on the server computer, and generate a key pair for it.
Define the user on the client computer, and generate a key pair for it.
Define the web site on the client computer, and cut paste it's public key from the server.
Define the user on the server computer, and cut paste it's public key from the client.

It means that, in order to generate the user key pair, you have to run Pliant HTTP server locally.

File	Content
`site.pdb`	The web sites definition. You can copy this file to all your systems, and don't need to keep it secret. On the other hand, anybody that succeed to change this file can get administrator right on the HTTP server, so can probably also corrupt all your system.
`site_secret.pdb`	The web sites private keys in clear text. You have to keep this file secret: anybody that succeed to read it can bypass the Pliant HTTP server security mechanism, can probably also corrupt the all server content, and can make clients believe that one of his systems is this HTTP server.
`user.pdb`	The users definition. You can copy this file to all your systems, and don't need to keep it secret. On the other hand, anybody that succeed to change this file can get administrator right on the HTTP server, so can probably also corrupt all your system.
`user_secret.pdb`	The users private keys, ciphered using the users password. You should keep this file secret. If somebody succeed to read this file, then he still does not have the users private keys until he can also get the user password for the key, but most of the time, it's easier to brake the user password than to brake the key.

Nb: These files are stored in Pliant security:/ directory which is /pliant_security/ system directory on this server.

Another solution for configuring Pliant HTTP server both on a server and on a client computer is to configure everything locally on the server computer, then copy site.pdb , user.pdb and user_secret.pdb on the client, and finally remove user_secret.pdb on the server computer (also removing is recommended, not necessary).
So, on the server you end with: site.pdb site_secret.pdb user.pdb
and on the client, you end with: site.pdb user.pdb user_secret.pdb
If you do things the other way round (configure everything on the client), then copy to the server, then you should also not use the network to copy the files from the client to the server since a network sniffer could pick site_secret.pdb content on the fly, so it's not recommended.

Static pages can be written either in HTML format or .page format.
On the other hand, if you are using Pliant HTTP server, dynamic pages have to be written using .page format, which is translated to HTML on the fly by the Pliant HTTP server.
.page format documentation

When the requested page does not point to a .page or static file, the Pliant HTTP server will look for a virtual tree.
As an example, if you request /abc/def/ghi/jkl.html and there is no /abc/def/ghi/jkl.html or /abc/def/ghi/jkl.page file, then the server will successively try to execute:
/abc/def/ghi/virtual_tree.page /abc/def/virtual_tree.page /abc/virtual_tree.page /virtual_tree.pageIf one such page exists, while it's executed, the 'virtual_path' variable is set with the subpath that have been removed to find the virtual page.

You can find an example in virtual_tree.page and virtual_tree_PUT.page that implement Pliant files and data browser.

If the clients sends a PUT HTTP request, the same mechanism is applyed, but the virtual page name must be virtual_tree_PUT.page
and while the virtual page is executed, the 'http_request:put_file' variable is the name of the file that has been sent.

If the clients sends a DELETE HTTP request, the same mechanism is applyed, but the virtual page name must be virtual_tree_DELETE.page

This is a sample style sheet that you could call sample.style :

module "/pliant/protocol/http/server.pli" module "/pliant/protocol/http/style/default.style" method p highlight msg arg_rw HtmlPage p ; arg Str msg strong_definition p font color (color hsl 60 100 50) p small p text msg export '. highlight'

Please notice the 'strong_definition' that has been included in the new 'highlight' function and means that the new definition will take on existing ones.

Then you want to apply the new style sheet to an existing .page file, you just include the module:

module "sample.style" text "This is the text " ; highlight "with it's highlighted part"

So, the final result is:

Instead of:

This is the text with it's highlighted part

This sample is available in /pliant/protocol/http/style/ directory.

server.pli	contains the HTTP protocol layer. It uses several common services defined in /pliant/protocol/common/
style/common.pli	a set of functions that will be usefull for defining styles
style/common.style	most styles will include this one as a submodule: it provides some basic instructions that produce nothing visible but rather drive the browser or check the environment.
style/default.style	is the style sheet that defines the keywords available when using .page format
style/untrasafe.style	a .page file using this style cannot corrupt the HTTP server: all the intructions defined in the .page format are available, but no computation can be done.
filters.pli	is used to define some filters that will translate some text files to .page (dynamic filter) or something else such as HTML (static filter). The filter is selected from the extension of the file, so at the end, you get pretty displaying for several text files formats.

Listening for clients on the TCP ports is handled by tcp_server.pli module that will then create a new thread and call the 'service' method of the HTTP server.
The 'service' method will mainly loop on the 'parse_then_answer' method which is responsible for handling one request.
- 'parse_then_answer' will first scan all the lines of the client request header.
- then it will use the informations in the header to determine the user which is submitting the request, the site and area concerned by the request, and the user rights.
- the biggest part of the 'parse_then_answer' function is the one that handles multipart POST forms. If the form is multipart, then Pliant HTTP server will store uploaded files in temporary files and convert others so that it looks as is if the form add been submitted without multipart.
Finally, most of the time, since it's a GET request, 'parse_then_answer' will call 'answer' method.
'answer' method is mapping the URL to a real file using 'what_file' method that will add the site root path in front of the URL.
- 'answer' method will first check if the user is allowed to access the URL, and if not, it will send /misc/not_allowed.html page
- then it will try to provide the requested file through calling 'send_file' method.
- then it will scan for a virtual tree page.
- and if nothing succeeded, it will send /misc/not_found.html page.
In 'send_file' method, we first try 'send_dynamic_file' then 'send_static_file'.
'send_dynamic_file' is handling dynamic files such as .page .pli .c files that translate to an executable function.
'send_static_file' is handling static files that the server will translate at run time.

The Pliant HTTP server uses the file extension to decide how to handle it.
The extensions are recorded using 3 functions:
'declare_mime_type' just specify the MIME type to associate to the file when answering a HTTP request.
'declare_mime_static_filter' provides a function that will translate the file on the fly at run time.
'declare_mime_dynamic_filter' provides a function that will translate the file to a Pliant program at compile time.
You can find sample filters in filters.pli

Pliant HTTP server maintains the set of dynamic pages in a dictionary called 'dynamic_pages'
Each page is convered from a .page source file (by the 'compile_dynamic_page' method) to a Pliant function that will be stored in the dictionary. This is done using a very classical Pliant mechanism: add a small header on top of the .page source code, then compile it using the standard 'compile_text' Pliant function.
When a dynamic page is called, the function is retreved from the dictionary, then checked for consitency (if the source code file has changed, then it will be automatically recompiled) and finally executed.

What's stronger in this system is the subpages notion. A subpage is what will be executed when you click on a button. The subpage is also recorded in the dictionary when the main one is, but it's a more sophisticated thing: it also is a function that will be executed, but this function has an environment parameter, which is a Pliant type that contains one field for each local variables that is expected to be passed from the main page to the subpage.When the function is executed in 'send_dynamic_file' method, the environement is scanned (the HTTP form, and the URL options) for local variables values, and these will be checked against the server signature (in order to protect against the client changing them), then copyed in the instance of the subpage function context data type.

In simple words, if you write this in a .page:

var Int i := 5 button "press me" text "the value of i was "+string:i

then it will display 'the value of i was 5' because what's under the button will be recorded as a subpage, and this one will have a context type containing a 'i' field. So, in the main page, when reaching the button position, Pliant will encode, then sign, then send the 'i' value to the browser, and when you press the button, the browser will send it back to the server that will copy it to the context it will pass to the subpage. As a result, Pliant HTTP server machinery has completely hidden to your application the stateless nature of the HTTP protocol.

Of course, there is something magic here since the code handling dynamic page is so small, and it's the 'freeze' method defined in freeze.pli module that is responsible for deciding which variables needs to be copyed, and compile the subpart of the function as a new function that will get the variables value from the enviroment structure rather than allocating them on the stack, but it's not at all something specific to the HTTP server. As an example, it's also used by 'thread' control.

Now you can read the code, it's only roughly 1000 lines in a single server.pli module, so an advanced programmer might be abble to read it in a single day and that's the utltimate justification of Pliant.

The current status of the HTTP server is described in the HTTP server section of the Pliant overall project.