# Server/script protocol

## Introduction

Script execution involves 3 processes: a client process running a WWW browser; the HTTP server process; and a DECnet netserver process which executes the WWWEXEC command procedure (or other object). These processes shall be referred to as the Client, the Server, and the Scriptserver in the following description.

For a script to execute, the Client first connects to the Server and makes an HTTP request (e.g. POST) that triggers script execution in the Server. The Server creates a DECnet logical link to the WWWEXEC object, which creates the Scriptserver process. Starting with version 1.8 of the server, the Scriptserver process may be another thread within the server process itself rather than a DECnet task.

## Connection data (always sent)

After the logical link is established, the Server always sends the following 4 data messages to the Scriptserver:

subfunction
  String representing the function that the server wishes to provide, either "SEARCH" "HTBIN", "POST", or "CONVERT".

method
  This string is the METHOD field parsed from the HTTP request, usually GET. This field is truncated to 255 characters before being sent.

protocol
  This string is the HTTP protocol (e.g. HTTP/V1.0) parsed from the request. If the request is from a 0.9 client, this string is null. This field is truncated to 255 characters before being sent.

URL-ident
  File identifier parsed from the URL in the request (ident is portion before ? or # in URL). The string sent by the server is the translated ident (i.e. actual file path), not the ident path from the URL itself. Only first 255 characters of this field are sent.

## Commands

The HTTP server then lets the script execution process control the session by reading and responding to commands sent over the DECnet link by the Scriptserver:

<DNETARG>
  Requests Server to send Scriptserver the search argument parsed from URL of request. If the argument was generated by an HTML form, the response message may be quite long. (Not readable by DCL).

<DNETARG2>
  Same as <DNETARG> except that argument is truncated to 255 characters to allow reading by DCL.

<DNETPATH>
  Requests Server to send Scriptserver the matching portion of the translated URL that caused the the script to be invoked (e.g. "/HTBIN/"). The path in truncated to 255 characters and converted to upper case.

<DNETHDR>
  Requests Server to send Scriptserver the HTTP request header lines sent by the Client to the Server. Last line sent will be a zero-length line.

<DNETINPUT>
  Requests Server to read data from Client TCP connection and relay to the Scriptserver. Only one DECnet message is sent. If more data is still needed, another input request must by made by the Scriptserver.

<DNETTEXT>
  Requests Server to send Client an HTTP protocol response with a content-type of "text/plain" and follow with data read from the Scriptserver. The Scriptserver will first send an HTTP status line (e.g. 200 sending doc) follow it with text that is to appear in the user's output window.

  Data is sent assuming implied carriage control, the Server appends a newline (CRLF) to each DECnet message it recieves over the logical link. The Scriptserver marks the end of the text data by sending a line consisting solely of the string "</DNETTEXT>". Server will close the connection after processing this tag.

<DNETRAW>
  Requests Server to read DECnet data 'raw' from scriptserver and send to Client. The Scriptserver is responsible for formatting the entire response in conformance with the HTTP protocol (including carriage control characters). End of data is flagged by a DECnet message consisting of solely of"</DNETRAW>", which will cause Server to close connection.

<DNETCGI>
  Request Server to read DECnet data 'raw' and interpret data sent by Scriptserver as CGI (Common Gateway Interface) script output. If first line is "location: ", a redirect is performed. End of data is flagged by "</DNETCGI>".

<DNETRECMODE>
  Request Server to process any subsequent <DNETRAW> or <DNETCGI> commands in record mode rather than stream mode. In record mode, an implied CR/LF pair is appended to each network message, making it easier for scripts to append output directly to the network link. In record mode, the maximum record length is reduced by 2 to 4094.

<DNETRQURL>
  Requests Server to send Scriptserver the actual URL (prior to rule file transformations) specified in the Client's request. A single DECnet message is sent.

<DNETBINDIR>
  Requests Server to send Scriptserver the htbin directory string as defined in the rule file.

<DNETHOST>
  Requests Server to send Scriptserver the http_default_host environment variable (host name to use in constructing URLS).

<DNETID>
  Requests Server to send Scriptserver the server version, the http_default_host environment variable, the local port for the connection and the remote port and host address. A single message is sent with the items separated by spaces. Note that the remote address is sent as a signed 32-bit value.

<DNETXLATE>
  Requests Server to read a URL from the Scriptserver, translate it according to rule file rules, and send the Scriptserver the result.

<DNETXLATEV>
  Functions same as <DNETXLATE> except that server checks if path is protected and returns null result if so. Note that server does not check file protection, just server-based protections. The access check is done against the method in the original request but may be overridden by prefixing the path string with "(method)" (e.g. "(GET)/~nee/index.html)

<DNETINVCACHE>
  Requests Server to invalidate the document cache, forcing all subsequent file accesses to read the latest copy of files from disk. The Server will send no response.