(* $Id: fcgi.isl,v 1.2 1996/02/23 01:26:27 connolly Exp $ *)
interface fcgi;

(*
The asynchronous calls going all over the place obscure the
interface a bit, so let me draw a picture:


	Web Server			App	Request
	(dispatcher)
	1.	--app.getvalues()------->
	2.     <----return--------------
	3.      --app.beginrequest()---->
	4.      --request.params()-------------->
	5.      --request.stdin()--------------->
	        --request.stdin()--------------->
	6.     <----dispatcher.stdout()---------
	       <----dispatcher.stdout()---------
        7.     <----dispatcher.endrequest()-----


 Between 3 and 7, the dispatcher may call request.abort().

 Calls to dispatcher.stdout() may be interspersed with calls
 to dispatcher.stderr().

 In the case of a filter, the dispatcher may call request.data()
 as well as request.stdin().
*)


type Dispatcher = object
	singleton "@@"
	brand "FCGI_VERSION_1"

	documentation "The dispatcher is the object in the web
	server that applications communicate with. It dispatches
	requests to App objects, and collects the replies.

	Language bindings of this interface must provide a mechanism
	for App object to find the relavent dispatcher for sending
	responses."

	methods
		stdout(r: Request, d: OctetSequence) = 6,
		stderr(r: Request, d: OctetSequence) = 7,
		endRequest(r: Request, appStatus: CARDINAL,
			   protocolStatus: ProtocolStatus) = 3
		end;

type ProtocolStatus = enumeration
   requestComplete,
   cantMpx, overloaded, unknownRole
end;

type App = object
	supertypes Manager end
	singleton "@@"
	brand "FCGI_VERSION_1"

	DOCUMENTATION "This is the FCGI application object.
	It supports the management interface (see below), and
	a method for beginning a request.

	The dispatcher specifies the object identifier
	of the request object in the beginRequest call. This
	call also specifies the role of the request handler (akin
	to its type) and optionally, a flag transferring control
	of the transport connection to the application."

	methods
		asynchronous beginRequest(r: Request,
			role: Role,
			flags: FlagSet) = 1
	end;

type Role = enumeration
	(* @@ replace with ILU type??? *)
	Responder, Authorizer, Filter
	end;

type FlagSet = byte;
constant KeepConn  : FlagSet = 1;

type Manager = object
	DOCUMENTATION "This is the FCGI application management object.
	It is implemented by the fcgi client library, and manages
	connection information."

	singleton "@@"
	brand "FCGI_VERSION_1"
	methods
		getValues(names: NVPairs): NVPairs = 9 "A dispatcher
			asks and application for the values of certain
			parameters:
				maxConns  : maximum number of
					concurrent transport connections
				maxReqs   : maximum number of concurrent
					requests
				mpxsConns : can connections be multiplexed?
			The response pairs the names with their values.
			Unknown names should be omitted from the response."
	end;

constant maxConns  : Name = "FCGI_MAX_CONNS";
constant maxReqs   : Name = "FCGI_MAX_REQS";
constant mpxsConns : Name = "FCGI_MPXS_CONNS";

type NVPairs = sequence of NameValue;

type NameValue = record
	name: Name,
	value: Value
	end;

type Name = ilu.CString;
type Value = ilu.CString;
type OctetSequence = sequence of byte;

type Request = object

	documentation "This is the object that actually handles
	a request. It receives the CGI environment via parameters,
	followed by some role-specific calls. The dispatcher may
	abort the request in response to a broken connection from
	a client."

	brand "FCGI_VERSION_1"
	methods
		asynchronous params(p: NVPairs) = 4, (* stream *)
		asynchronous abort() = 2
		end;

type Responder = object
	brand "FCGI_VERSION_1"
	supertypes Request end

	documentation "This is the traditional CGI role: receive
	input on stdin, emit a response on stdout, and any errors
	to stderr."

	methods
		asynchronous stdin(d: OctetSequence) = 5
		end;

type Authorizer = object
	brand "FCGI_VERSION_1"
	supertypes Request end

	documentation "This object makes authorization decisions.
	For 'yes', it sends a 200 status line to stdout. For a 'no',
	it sends a full HTTP response with any other status code
	to stdout."
	;

type Filter = object
	brand "FCGI_VERSION_1"
	supertypes Responder end

	documentation "This object combines data stored at the
	server with data supplied by the content to formulate a response."

	methods
		asynchronous data(d: OctetSequence) = 8
		end;