EWF/EWSGI-specification.md

**WARNING** **THIS PAGE IS IN PROGRESS, AS IT IS NOW, IT NEEDS UPDATE SINCE IT DOES NOT REFLECT THE FUTURE INTERFACE**

# The Eiffel Web Server Gateway Interface
## Preface 
This specification is a proposition based on recent discussion on the mailing list.
This is work in progress, so far nothing had been decided.
You can find another proposal at http://eiffel.seibostudios.se/wiki/EWSGI , it has common background and goal, however still differ on specific parts.
The main goal for now is to unified those 2 specifications.

---
Note the following is work in progress, and reflect a specification proposal, rather than the final specification.
2011-08-01
---
For now, the specification from EWF is done in Eiffel interface
please see: https://github.com/Eiffel-World/Eiffel-Web-Framework/tree/master/library/server/ewsgi/specification

WGI_APPLICATION

    deferred class 
    	WGI_APPLICATION
    
    feature {NONE} -- Execution
    
    	execute (req: WGI_REQUEST; res: WGI_RESPONSE_BUFFER)
    			-- Execute the request
    			-- See `req.input' for input stream
    			--     `req.environment' for the Gateway environment	
    			-- and `res' for the output buffer
    		require
    			res_status_unset: not res.status_is_set
    		deferred
    		ensure
    			res_status_set: res.status_is_set
    			res_committed: res.message_committed
    		end
    	
    end

WGI_REQUEST

	deferred class 
		WGI_REQUEST
	feature -- Access: Input
	
		input: WGI_INPUT_STREAM
				-- Server input channel
			deferred
			end
		
	feature -- Access: extra values
	
		request_time: detachable DATE_TIME
				-- Request time (UTC)
			deferred
			end
		
	feature -- Access: CGI meta variables		
	
		meta_variable (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32
				-- Environment variable related to `a_name'
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
		meta_variables: HASH_TABLE [READABLE_STRING_32, READABLE_STRING_GENERAL]
			deferred
			end
	
	feature -- Query string Parameters
	
		query_parameters: HASH_TABLE [READABLE_STRING_32, READABLE_STRING_GENERAL]
				-- Variables extracted from QUERY_STRING
			deferred
			end
	
		query_parameter (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32
				-- Parameter for name `n'.
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
	feature -- Form fields and related
	
		form_data_parameters: HASH_TABLE [READABLE_STRING_32, READABLE_STRING_GENERAL]
				-- Variables sent by POST request
			deferred
			end
	
		form_data_parameter (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32
				-- Field for name `a_name'.
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
		uploaded_files: HASH_TABLE [WGI_UPLOADED_FILE_DATA, READABLE_STRING_GENERAL]
				-- Table of uploaded files information
				--| name: original path from the user
				--| type: content type
				--| tmp_name: path to temp file that resides on server
				--| tmp_base_name: basename of `tmp_name'
				--| error: if /= 0 , there was an error : TODO ...
				--| size: size of the file given by the http request
			deferred
			end
			
	feature -- Cookies	
	
		cookies: HASH_TABLE [READABLE_STRING_32, READABLE_STRING_GENERAL]
				-- Expanded cookies variable
			deferred
			end
	
		cookie (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32
				-- Field for name `a_name'.
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
	feature -- Access: global variable
	
		parameters: HASH_TABLE [READABLE_STRING_32, READABLE_STRING_GENERAL]
				-- Table containing all the various variables
				-- Warning: this is computed each time, if you change the content of other containers
				-- this won't update this Result's content, unless you query it again
			deferred
			end
	
		parameter (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32
				-- Variable named `a_name' from any of the variables container
				-- and following a specific order
				-- execution, environment, get, post, cookies
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
	feature -- Uploaded File Handling
	
		is_uploaded_file (a_filename: STRING_8): BOOLEAN
				-- Is `a_filename' a file uploaded via HTTP POST
			deferred
			end
		
	feature -- URL Utility
	
		absolute_script_url (a_path: STRING_8): STRING_8
				-- Absolute Url for the script if any, extended by `a_path'
			deferred
			end
	
		script_url (a_path: STRING_8): STRING_8
				-- Url relative to script name if any, extended by `a_path'
			require
				a_path_attached: a_path /= Void
			deferred
			end
		
	end

WGI_RESPONSE_BUFFER

	deferred class
		WGI_RESPONSE_BUFFER
	
	feature {WGI_APPLICATION} -- Commit
	
		commit
				-- Commit the current response
			deferred
			ensure
				status_is_set: status_is_set
				header_committed: header_committed
				message_committed: message_committed
			end
	
	feature -- Status report
	
		header_committed: BOOLEAN
				-- Header committed?
			deferred
			end
	
		message_committed: BOOLEAN
				-- Message committed?
			deferred
			end
	
		message_writable: BOOLEAN
				-- Can message be written?
			deferred
			end
	
	feature {WGI_RESPONSE_BUFFER} -- Core output operation
	
		write (s: STRING)
				-- Send the string `s'
				-- this can be used for header and body
			deferred
			end
	
	feature -- Status setting
	
		status_is_set: BOOLEAN
				-- Is status set?
			deferred
			end
	
		set_status_code (a_code: INTEGER)
				-- Set response status code
				-- Should be done before sending any data back to the client
			require
				status_not_set: not status_is_set
				header_not_committed: not header_committed
			deferred
			ensure
				status_code_set: status_code = a_code
				status_set: status_is_set
			end
	
		status_code: INTEGER
				-- Response status
			deferred
			end
	
	feature -- Header output operation
	
		write_headers_string (a_headers: STRING)
			require
				status_set: status_is_set
				header_not_committed: not header_committed
			deferred
			ensure
				status_set: status_is_set
				header_committed: header_committed
				message_writable: message_writable
			end
	
		write_header (a_status_code: INTEGER; a_headers: detachable ARRAY [TUPLE [key: STRING; value: STRING]])
				-- Send headers with status `a_status', and headers from `a_headers'
			require
				status_not_set: not status_is_set
				header_not_committed: not header_committed
			deferred
			ensure
				header_committed: header_committed
				status_set: status_is_set
				message_writable: message_writable
			end
	
	feature -- Output operation
	
		write_string (s: STRING)
				-- Send the string `s'
			require
				message_writable: message_writable
			deferred
			end
	
		write_substring (s: STRING; a_begin_index, a_end_index: INTEGER)
				-- Send the substring `s[a_begin_index:a_end_index]'
			require
				message_writable: message_writable
			deferred
			end
	
		write_file_content (fn: STRING)
				-- Send the content of file `fn'
			require
				message_writable: message_writable
			deferred
			end
	
		flush
				-- Flush if it makes sense
			deferred
			end
	
	end


## Proof-of-concept and reference implementation

# Specification overview

## The Server/Gateway Side

## The Application/Framework Side

## Specification Details

## Implementation/Application Notes

## Questions and Answers 

## Proposed/Under Discussion 

## Acknowledgements 

## References