---

PDepp Webserver Programmer's Manual

PDEPP Webserver pre 0.3.1

Introduction To The Code

License & Disclaimer

PDEPP Webserver pre 0.3.1
Copyright (C) 2001 by Christian Hoenig & Gunter Ohrner
<pdepp@CustomCDROM.de>
PDEPP Webserver comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. For more details see the GNU General Public License Version 2 (http://www.gnu.org/copyleft/gpl.html).

Overview / Design Goals

One major goal while designing the PDepp Webserver was to keep the whole program as modular as possible, with well defined, consistent interfaces and with each module knowing the least possible about any other module. It should be possible to replace the server's protocol parser or network layer with no changes to other parts of the server.

Furthermore it should be possible for several alternative implementations of a given module to coexist and for the "right" implementation to be selected dynamically at runtime (eg. choosing a different request handler depending on the URLs path prefix or file extension, details see below), however this has not been implemented yet. Adding it should not be too hard and would mainly consist of wrapping the existing module interfaces into structs (using function pointers) to allow them beeing put in lists.

Most modules are ADTs, very closely resembling the the structure of classes in object oriented programming languages. This way we tried to achieve the neccessary level of abstraction and data encapsulation.

Key Features From The Programmer's / Contributor's Point Of View

• clean internal structure ( The PDepp Webserver's Structure )
• consistent syntactical programming style throughout the whole program ( Syntactical Programming Conventions )
• probably easy portable to virtually all Unix-based platforms as it does already run on quite a few and uses autoconf to be easily adaptable for new platforms.
• automatically ./configure -able for memory debugging and profiling
• includes easily customizeable high performant data type independent doubly linked list and hash table templates

Please refer to the Bug List and the Todo List in this manual for known bugs and limitations.

Latest Changes

0.3 Gargle Blaster

• redesigned logger subsystem completely. The api is basically the same (and has not changed at all since 0.3pre). (logger.h / logger.c)
• new data structure template: hash table using external hashing (xhash_tmpl_h.inc / xhash_tmpl_c.inc)
• MIME type management (mime.h / mime.c)
• signal handlers (signal_handler.h / signal_handler.c)
• improved HTTP parser (http.h / http.c)
• moved some functions of general interest into misc.c (misc.h / misc.c)
• tons of improvements, compatibility and bug fixes everywhere
• major changes to the build system

0.2 Improbability Drive

• added Connection Handler layer (conn_handler.n / conn_handler.c)
• added Protocol Handler layer (http.h / http.c)
• added Data Request Handler Layer (reqhandler_file.h / reqhandler_file.c)
• added data structure template: doubly linked list (mlist_tmpl_h.inc / mlist_tmpl_h.inc)
• major changes to the build system

0.1 Initial Release

Syntactical Programming Conventions

Altough we understand that there is a myriad of ways to write syntactically correct code and many of these may be help- and / or useful in some cases it is of extreme importance that only exactly ONE is used within one specific program. There are only very few things worse than mixed coding styles in one program...

The following rules and conventions are used within PDepp Webserver's code.

Naming Conventions:

• functionNames / methodNames start with a lower-case letter, do exclusively contain letters and digits and the first letter of any distinct word in a composite name must be upper case.
• variable_names are all lower case, several distinct words joined into one name are separated by underscores.
• DatatypeNames / StructNames are all lower case - except of the very first and the first letters in of each distinct word in a composite name which must be capital letters - and consist only of letters and digits.
• file_names are all lower case but may contain underscores.

Structural Conventions:

• Indentation at the start of a command must be done with tabs. If the whole command is split across several lines, the second and all following lines (the continued line ) must be indented with exactly the same amount of tabs as the start of the command. After that spaces must be used to further indent the continued line, the first non-space character must be placed exactly one character right of the position of the first opening bracket in the start of the command if there is any. If there is none or if there is an obviously better way to indent a given contined line, this rule may be ignored.
• Indentation in a line after one or more non-whitespace characters (eg. formatting within a comment) must be done with spaces.
• The opening bracket "{" of a command block must be placed on a separate line with the same indentation as the previous line. In case of an "else" branch of an "if" block the closing bracket of the block before, the keyword "else" and the opening bracket of the "else" command block may be placed in a single line.
• The indentation of all lines within a command block must be one tab larger than the indentation of the lines surrounding the block.

The PDepp Webserver's Structure

The PDepp Webserver's architecture is based on several independant layers. Each layer has (or at least should have ;-) a well-defined interface and task scope. Each layer does only know about and communicate with it's direct neighbours and is designed to be easily replaceable by an alternate implementation without affecting any other layer it's communicating to.

The server's basic structure can be seen best in the following overview diagram. The "layers" are aligned from the left to the right as we simply could not agree on the Server Core being top or bottom of the architecture ;-). Having this diagram's layout in mind we will refer to a layer's "left neighbour" and "right neighbour" throughout the rest of the manual.

PDepp Webserver's layered architecture

The Generic Layer Interface

Each layer has a predefined set's of methods it must implement. Unfortunately C has nothing resembling C++'s pure virtual classes or Java's Interfaces which would be a nice way to enforce a consistent interface so in our case it's completely up to the Layer's programmer to stick to the standard.

An important thing to note is that the right neighbour of ANY layer is passive - it waits for a request or notification from its left neighbour before doing anything. In this context the Client could be seen as the Server Core's left neighbour.

Each Layer has to provide the following methods (the Server Core being a slight exception as its "left neighbour" is non-standard as well by design):

• Init
  "Constructor": Create a new object of this type.
• Receive
  Notification from the left neighbour that there is new data waiting to be read.
• Send
  Request from the left neighbour to send all data currently available.
• Process
  Request from the left neighbour to "process some data", that is to do some work now that needs to be done anyway.
• IsDataPending
  Query from the left neighbour if we have any data left to send.
• Terminate
  "Destructor": Terminates the given object of this type.

The Server Core Layer

The Server Core is the connection multiplexer part of the PDepp Webserver. It listens for and accepts new connections, creating a new Connection Handler object to manage it. Additionally it waits for data arriving for currently active connections or for active sockets ready to send data and informs the corresponding Connection Handler by calling its chReceive or chSend functions.

The Server Core's interface is declared in server.h. Its currently only implementation resides in server.c , supports TCP/IP sockets and has not yet been converted to an ADT.

Todo:

Both the connection multiplexer and the Connection Handler should be independant of the actual kind of connection used (TCP sockets, unix domain sockets, named FIFOs, etc...) and work only on file descriptors. Maybe an additional abstraction layer for different kinds of communication should be introduced... (eg. renaming the Server Core to "Connection Multiplexer" and creating a new Server module / layer containing the code to establish a "server socket" and accepting new connections.) \n

The Connection Handler Layer

A Connection Handler represents a single connection to a client. It's responsible for non-blocking reads into the receive buffer and for writing chunks from the send buffer to the client. A connection handler associates a connection with a protocol Handler.

The Connection Handler's interface is declared in conn_handler.h. Its currently only implementation resides in conn_handler.c and supports client connections through file descriptors.

The Protocol Handler Layer

A Protocol Handler is responsible for "understanding" the client's requests and giving the right answers (ofter with the help of a Request Handler). The whole protocol parser / generator code is encapsulated in modules belonging to this layer.

The Protocol Handler's interface is currently declared in http.h . Its currently only implementation resides in http.c , supports a subset of the HTTP 1.0 protocol and virtually no HTTP 1.1 extensions.

Possible alternative implementations could include a Protocol Handler supporting the FTP protocol or similar (NNTP, ...).

The Request Handler Layer

A Request Handler is responsible for actually executing the request of the client as understood by the Protocol Handler and returning the data resulting from processing the request.

The Request Handler's interface is currently declared in reqhandler_file.h. Its currently only implementation resides in reqhandler_file.c and supports reading static files from disk.

Possible alternative implementations could include a Request Handler supporting CGI scripts or database querys.

Other Modules / Non-Layer Modules

All additional modules in alphabetical order:

• buffer.h / buffer.c
  utility functions to create a struct Buffer or struct Buffer*. (buffer control blocks)
• buflist.h / buflist.c
  ADT: a list of struct Buffer's. mlist_tmpl-adapter.
• char_xhash.h / char_xhash.c
  ADT: a hash table using external hashing for storing char*s. xhash_tmpl-adapter.
• chrlist.h / chrlist.c
  ADT: a list of char*s. mlist_tmpl-adapter.
• conftable.h / conftable.c
  utility functions for storing and retrieving configuration values and for reading configuration files.
• conn_handler_list.h / conn_handler_list.c
  ADT: a list of Connection Handler-objects. mlist_tmpl-adapter.
• intlist.h / intlist.c
  ADT: a list of integers. mlist_tmpl-adapter.
• keylist.h / keylist.c
  ADT: a list of key-value-pairs. mlist_tmpl-adapter.
• logger.h / logger.c
  ADT: representation of a "log file" and utility functions for logging messages
• logger_list.h / logger_list.c
  ADT: a list of Logger objects. mlist_tmpl-adapter.
• mime.h / mime.c
  utility functions for storing and looking up MIME types corresponding to a given file extensions.
• misc.h / misc.c
  miscellaneous utility functions
• signal_handler.h / signal_handler.c
  utility functions for signal handling
• tmpl_common.h
  helper macros for creating data type independant module templates
• xmalloc.h / xmalloc.c
  utility functions for memory (re-/de-)allocation.

Data type independant container templates in alphabetical order:

• mlist_tmpl_h.inc / mlist_tmpl_c.inc
  data type independant doubly linked list template.
• xhash_tmpl_h.inc / xhash_tmpl_c.inc
  data type independant hashing table (external hashing using mlist_tmpl).

---