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

EWSGI_APPLICATION

    deferred class 
    	EWSGI_APPLICATION
    
    feature {NONE} -- Execution
    
    	execute (req: EWSGI_REQUEST; res: EWSGI_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

EWSGI_REQUEST

	deferred class 
		EWSGI_REQUEST
	feature -- Access: Input
	
		input: EWSGI_INPUT_STREAM
				-- Server input channel
			deferred
			end
		
	 feature -- Access: extra values
	
		request_time: detachable DATE_TIME
				-- Request time (UTC)
			deferred
			end
		
	feature -- Access: environment variables		
	
		environment: EWSGI_ENVIRONMENT
				-- Environment variables
			deferred
			end
	
		environment_variable (a_name: STRING_8): detachable STRING_8
				-- Environment variable related to `a_name'
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
		
	feature -- Access: execution variables		
	
		execution_variables: EWSGI_VARIABLES [STRING_32]
				-- Execution variables set by the application
			deferred
			end
	
		execution_variable (a_name: STRING_8): detachable STRING_32
				-- Execution variable related to `a_name'
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
		
	feature -- URL Parameters
	
		parameters: EWSGI_VARIABLES [STRING_32]
				-- Variables extracted from QUERY_STRING
			deferred
			end
	
		parameter (a_name: STRING_8): detachable 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_fields: EWSGI_VARIABLES [STRING_32]
				-- Variables sent by POST request
			deferred
			end
	
		form_field (a_name: STRING_8): detachable 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 [EWSGI_UPLOADED_FILE_DATA, STRING_8]
				-- Table of uploaded files information
			deferred
			end
		
	feature -- Cookies	
	
		cookies_variables: HASH_TABLE [STRING_8, STRING_8]
				-- Expanded cookies variable
			deferred
			end
	
		cookies_variable (a_name: STRING_8): detachable STRING_8
				-- Field for name `a_name'.
			require
				a_name_valid: a_name /= Void and then not a_name.is_empty
			deferred
			end
	
		cookies: HASH_TABLE [EWSGI_COOKIE, STRING_8]
				-- Cookies Information
			deferred
			end
		
	feature -- Access: global variable
	
		variables: HASH_TABLE [STRING_32, STRING_32]
				-- 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
	
		variable (a_name: STRING_8): detachable 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

EWSGI_RESPONSE_BUFFER

	deferred class 
		EWSGI_RESPONSE_BUFFER
	
	feature {EWSGI_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 {NONE} -- Core output operation
	
		write (s: STRING_8)
				-- 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_32)
				-- 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_32
				-- Response status
			deferred
			end
		
	feature -- Output operation
	
		flush
				-- Flush if it makes sense
			deferred
			end
	
		write_string (s: STRING_8)
				-- Send the string `s'
			require
				message_writable: message_writable
			deferred
			end
	
		write_substring (s: STRING_8; a_begin_index, a_end_index: INTEGER_32)
				-- Send the substring `s[a_begin_index:a_end_index]'
			require
				message_writable: message_writable
			deferred
			end
	
		write_file_content (fn: STRING_8)
				-- Send the content of file `fn'
			require
				message_writable: message_writable
			deferred
			end
		
	feature -- Header output operation
	
		write_header (a_status_code: INTEGER_32; a_headers: detachable ARRAY [TUPLE [key: STRING_8; value: STRING_8]])
				-- 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
			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