Home   Info   Documentation   Installation   Configuration   History   Download   Mailing list   Feedback 
 Up - Design   Back - Processes handling   Forward - API Library 

fhttpd user processes protocol

Protocol

fhttpd uses the same application protocol for pipes, AF_UNIX sockets and TCP/IP sockets, although while local processes, started by the server and connected through pipes don't require any authentication (if their executables are at their places in the filesystem, they definitely are created by some user, who has at least write access to them), remote processes are required to pass their names and username/password authentication information. The protocol is binary and uses 32-bit integers with network byte order, where applicable. Login sequence is character-based.

Login

HTTP server always acts as the server, user process module always acts as the client in the login procedure. Client authenticates to the server.

Local applications, connected through pipes or AF_UNIX sockets never use login sequence.

All messages in the login sequence are ASCII strings with <CR><LF> line delimiters. Client sends ASCII strings with <LF> or <CR><LF> line delimiters. General format of the message is the same as used in FTP protocol, so message identification by the client should be performed by the numeric response code.

  1. Client connects to the server at the listening port (configured in the configuration file as ProcessPort, default is 8000 or redefined in the fhttpd-decls.h file as PROCESSSERVER in the current implementation).

  2. Server responds "220 Process server ready."

  3. Client sends to the server "USER", <SP> and the username.

  4. Server responds like an FTP server, "331 Password required for username." means that PASS command should be used, "230 User username logged in." finishes the user authentication. All other responses are negative.

  5. If PASS is required, client sends to the server "PASS", <SP> and the password. Otherwise, skips to the step 7.

  6. Server responds like an FTP server, "230 User username logged in." finishes the user authentication, all other responses are negative.

  7. Client sends "APPLICATION", <SP> and the application name.

  8. Server responds, "200 OK" finishes the application login sequence, all other responses are negative.
Login sequence may fail because of wrong username, password, application name, mismatched username and application name, application instances limit and internal error. Failure causes client to be disconnected. After the finished login sequence (last <LF>s are sent from both server and client) binary protocol is used.

Messages from the HTTP server

HTTP server sends messages in the format:
buffsize
(32 bits)		id
(32 bits)		reqtype
(32 bits)
rlsize
(32 bits)		rl
(rlsize bytes)
nlines
(32 bits)		 lines
(nlines line blocks)
databuffsize
(32 bits)		data
(databuffsize bytes)

where:

buffsize
total size of the message in bytes (including itself).

id
request ID, assigned by the HTTP server

reqtype
request type

rlsize
request line size, including trailing zero

rl
request line, sent from the client, null terminated

nlines
the number of lines in parameters list

lines
parameters list represented as nlines line blocks

databuffsize
data buffer size

data
raw data, sent from the client, NOT null-terminated

request type
is one of the following:
ValueDefined asMeaning
1FHTTPD_REQUESTRequest received from the HTTP client
2FHTTPD_DISCONNECTHTTP client disconnected
3FHTTPD_ACKAcknowledge for sent block(s)
4FHTTPD_EXITOKConfirmation for exit request


line block
is:
paramc
(32 bits)		 psize1
(32 bits)		param1
(psize1
bytes)		 psize2
(32 bits)		param2
(psize2
bytes)		  ...  psizeparamc-1
(32 bits)		paramparamc-1
(psizeparamc-1
bytes)

where:

paramc
number of parameters in the line

psizen
length of the n-th parameter

paramn
n-th parameter



Messages to the HTTP server

Process module sends messages to the HTTP server in the format:
buffsize
(32 bits)		opnumber
(32 bits)		id
(32 bits)		data
(buffsize-24 bytes)

where:

buffsize
total size of the message in bytes (including itself).

id
request ID of the request, this message responds to

opnumber
operation number

operation number
is one of the following:
ValueDefined asMeaning
0FHTTPD_FINISHFinish response (no data)
1FHTTPD_SENDSend the provided data to the client
2FHTTPD_INST_SELECTSet instance selection for the provided data
3FHTTPD_INST_DESELECTRemove instance selection for the provided data
4FHTTPD_INST_CAPSet capabilities (data is a 32-bit integer containing bit-mapped capabilities)
5FHTTPD_FINISH_DROPFinish response (no data) and disconnect the client.
6FHTTPD_INST_EXITREQExit request (data is a 32-bit integer containing the request value )


capabilities
are bit-mapped:
ValueDefined asMeaning
1APP_CAP_KEEPALIVE"Keep-Alive" option supported
2APP_CAP_ACKFINISHSend FHTTPD_ACK message for blocks after finishing sending them


Data in messages from the HTTP server

Data in messages from the HTTP server is mostly similar to the data in CGI environment and stdin. Currently all lines in parameters list have two parameters - key and value. Keys are:
"HTTP_ACCEPT"
(CGI-compatible) Value is the Accept field in the HTTP request
"HTTP_IF_MODIFIED_SINCE"
(NOT CGI-compatible) Value is the If-Modified-Since field in the HTTP request converted to the integer time value
"HTTP_USER_AGENT"
(CGI-compatible) Value is the User-Agent field in the HTTP request
"REMOTE_ADDR"
(CGI-compatible) Value is the client's IP address in dot-notation
"REMOTE_HOST"
(CGI-compatible) Value is the client's full hostname (if resolved)
"REMOTE_USER"
(CGI-compatible) Value is the client's username (if user authentication is used)
"QUERY_STRING"
(CGI-compatible) Value is the parsed query string from the HTTP request
"CONTENT_LENGTH"
(CGI-compatible) Value is the Content-length field in the HTTP request (redundant, data buffer size contains the same value)
"CONTENT_TYPE"
(CGI-compatible) Value is the Content-type field in the HTTP request
"SERVER_PROTOCOL"
(CGI-compatible) Value is the HTTP protocol version (HTTP/0.9 and HTTP/1.0 are supported)
"REQUEST_METHOD"
(CGI-compatible) Value is the request method (GET, HEAD and PODT are supported, PUT is still reserved)
"SERVER_PORT"
(CGI-compatible) Value is the server port number (usually 80)
"SERVER_SOFTWARE"
(CGI-compatible) Value is the server software name (fhttpd currently uses "fhttpd/0.3.2")
"GATEWAY_INTERFACE"
(CGI-compatible) Value is the emulated CGI version ("CGI/1.1")
"SERVER_NAME"
(CGI-compatible) Value is the server's full hostname
"SCRIPT_NAME"
(CGI-compatible) Value is the parsed script name from the HTTP request
"SCRIPT_NAME_RESOLVED"
(NOT CGI-compatible) Value is the parsed script name from the HTTP request resolved to the local absolute pathname.
"HTTP_whatever"
(CGI-compatible) Any additional fields from the HTTP request
"KEEPALIVE"
(NOT CGI-compatible) Value is "Y" if Keep-Alive option is used
data is the raw data, sent from the HTTP client (if any) after the header. It isn't parsed in any way and isn't null-terminated.

Data in messages to the HTTP server

FHTTPD_FINISH

No data, message means that the response for some HTTP request with provided ID is finished.

FHTTPD_SEND

Data is the response for the HTTP request with provided ID. Response should be sent to the client at this point (it can be delayed because of the limited network throughput), but some parts of the response may be sent later, until FHTTPD_FINISH message will be sent. Server doesn't parse the data.

FHTTPD_INST_SELECT

Data is the list of parameters to instance selection. Message enables instance selection.

FHTTPD_INST_DESELECT

Data is the list of parameters to instance selection. Message disables instance selection.

FHTTPD_INST_CAP

Data is the 32-bit integer (network byte order) containing capabilities list.

FHTTPD_FINISH_DROP

No data, message means that the response for some HTTP request with provided ID is finished and client should be disconnected from the server.

FHTTPD_EXITREQ

Message means that process is requesting exit if the data is nonzero or canceling the exit request if the data is 0.

Receiving requests and sending responses

Requests are passed to processes in FHTTPD_REQUEST messages. If process is connected through AF_UNIX socket it may also receive a file handle of the socket, connected to the client. Requests are sent until the number of requests, sent to the instance and not completely answered by it reaches the queue limit, and if the queue limit is 1, only one requests can be sent to the instance at a time. Process should answer to the client and finish serving the request by sending FHTTPD_FINISH or FHTTPD_FINISH_DROP.

Data can be sent to the server in one or multiple FHTTPD_SEND messages or to the client directly if file descriptor is passed. If file descriptor was passed it should be closed after sending the response through it or at any time before FHTTPD_FINISH or FHTTPD_FINISH_DROP is sent if FHTTPD_SEND messages were used instead of it.

Instance selection

fhttpd can allow multiple instances of the same application to run simultaneously on one or several hosts. While not necessary for CGI-compatible applications, some applications may need to make sure that once some client's request was served by some application instance, all subsequent requests in the same "session" (whatever that may mean for the application) will be sent to the same instance, so all data, related to the "session" can be stored in memory instead of external files, passed through some kind of IPC, or sent back and forth between the client and server in HTML form's hidden fields.

Since instance selection is done in the server, some mechanism should determine situations, where such requests handling is necessary and give the server the data, by which instances will be selected. In HTTP there are three possible ways to positively identify the session:

(IP addresses aren't reliable enough to identify anything now - proxies and hosts with multiple users will make such identification unreliable).

Identification using hidden fields in forms isn't supported in fhttpd because the design of fhttpd was based on the assumption that the data, passed from the client can be anything, not necessary a form input, and the server shouldn't parse it even if it is a form.

HTTP cookies while being the most clean and reliable way to handle sessions, aren't supported by all HTTP clients, so both cookie-based and "ugly" URLs with session identifiers are supported.

To establish an instance selection, user process sends to the HTTP server FHTTPD_INST_SELECT message with 2 or 3 parameters in the data, separated by the <LF>:

3-byte operation
offset 0:
'A'
Accept matching queries. All queries with condition returning "true" will be sent to this instance.
'R'
Reject matching queries. All queries with condition returning "true" will NOT be sent to this instance.
offset 1:
'H'
Check header lines of the message, prepared to be sent to the application (NOT the request header itself) for matching strings.
'L'
Check request line for matching strings.
offset 2:
'E'
Condition returns "true" if the wildcard expression matches with the argument and "false" otherwise.
'N'
Condition returns "false" if the wildcard expression matches with the argument and "true" otherwise.


First parameter for wildcard matching:


Second parameter for wildcard matching:


Wildcard matching uses the same rules as shell wildcard matching, except for slash ('/') having no special meaning.

For the identifier in the HTTP cookie the request can be "AHE\nHTTP_COOKIE\nCSES=value*", and for the identifier in the URL the request can be "ALE\n*?CSES=value*" where "CSES" is the cookie key ("Client SESsion") and value is the cookie value. It's assumed that value doesn't contain any special characters for wildcard matching (or they are backslash-escaped) and has delimiters as first and last characters (the API library generates such cookies by itself).

Flow control

By default all flow control is handled by the server, and client just sends messages -- buffers will be sent to the client silently when client will be able to receive them. In some situations client may need to know when some data was actually sent (or at least, buffered) to support some flow control by itself -- for example for some streaming server. fhttpd allows the client to configure APP_CAP_ACKFINISH capability to get notified about blocks sent to the client. by FHTTPD_ACK messages. These messages contain no parameters and data is a 32-bit integer containing the number of buffers sent in response to some request (where request ID in the message indicates request) since the last FHTTPD_ACK message about the same request or since the beginning in the first message. Server does not guarantee that FHTTPD_ACK will be sent for every buffer, but it provides the number of sent buffers for the case when multiple buffers were written at once. It should be noted that "sent" doesn't mean that the data is actually arrived at the client or even was sent through the network interface -- buffering and delays obscure exact timing -- although for flow control needs it's enough.

Exit requests

Process can close its pipes or sockets and exit at any time, although that causes requests that are sent to it to be dropped. Since pipes and sockets do asynchronous data transfer, it's possible to drop the request while it's being sent from the server, so while it's acceptable for emergency exit, clean exit procedure should guarantee that no requests that are already sent to processes, are dropped.

Clean exit procedure requires sending an exit request and wait for a confirmation:

  1. Process module sends FHTTPD_INST_EXITREQ request with nonzero value to the server.
  2. Server continues sending and receiving messages for requests that are in progress, although does not send new requests to the instance that requested exit.
  3. When no requests are pending for the instance that requested exit, server sends FHTTPD_EXITOK to it.
  4. Process can exit.

At any time after FHTTPD_INST_EXITREQ request is sent process can send FHTTPD_INST_EXITREQ request with the value 0 to the server to cancel the exit request. That will cause HTTP server to continue sending requests to the process.

Alex Belits
Last modified: Wed Jun 23 04:26:13 PDT 1999
 Up - Design   Back - Processes handling   Forward - API Library 
 Home   Info   Documentation   Installation   Configuration   History   Download   Mailing list   Feedback