Http
The subsystem Http provides a minimal and safe subset of an HTTP/1.1 server running as a background action. It is minimal and safe in the sense that it does not handle any http request itself but delegates all requests to so-called servlets. The server only handles the http protocol, i.e. it listens on a local address, accepts connections, reads from and writes to a connection, and eventually closes a connection. The server is non-blocking.
The http server can be run with any protocol driver that provides CommStreams listeners. This includes CommTCP for running the server unencrypted over plain TCP/IP connections and HttpCommSSL for running as an https server over an SSL/TLS encrypted TCP/IP connection. The latter case requires additional openssl libraries, certificate and key files, and a basic understanding of SSL/TLS. For details please refer to the openssl documentation.
A servlet is registered for a particular prefix of the server's name space. It is the task of the servlet implementation to handle http requests directed to the name space part that is covered by the servlet. The implementation of a servlet may itself be inverted, i.e. it may be split into a sequence of continuations until a response is delivered. This enables long-running servlet implementations to be split into smaller pieces and allows for intertwined handling of multiple requests.
The design of the http server lends itself for implementing so-called REST APIs based on Component Pascal. By implementing and registering a servlet an application specific REST API can be easily provided without the complexities, safety issues, and interfacing problems of a full blown web server.
The http server itself does not introduce anything like a session state because http is a state-less protocol. However, sessions can be created easily by means of so-called cookies, which can be set and get via header fields. A session is a server side data structure identified by a unique id, e.g. a sequential number or a GUID. This id can be sent to the client upon creation of the session via a Set-Cookie response header field (rfc 6265). The Client will then add a Cookie request header field with the same content, viz. the session id, with future requests to the same site.
Limitations:
There is currently no support for named virtual hosts.
Currently supported URI formats: Request URIs are expected to be percent-encoded according to rfc 3986. The query part of a GET URI or a POST message content expects the content type application/x-www-form-urlencoded. Utf-8 is used as the character set.
Currently supported content encodings: There are no encodings other then the 'identity' encoding, i.e. no gzip or compress.
Two servlets are provided together with the http server:
- A SentinelServlet is registered for the empty name space prefix, i.e. it matches any request that is not handled by another servlet. Its task is to report an error message for any unhandled request.
- An EchoServlet is provided for testing and debugging purposes. Its task is to return the http request as its html result. This allows for inspection of http requests, in particular of the requested URI and the provided header fields and query parameters. The echo servlet is not registered by default.
An additional servlet (HttpWeb.Servlet) is provided for serving files located in a specified root folder. This servlet, although quite simple, turns an http server into a more traditional web server. For specifying a favorite web icon for your site another servlet (HttpWeb.FaviconServlet) is provided.