backup/EWF
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added subtree merged in doc/wiki

Browse Source
This commit is contained in:
Jocelyn Fiat
2012-05-15 18:26:08 +02:00
parent 1d89a2bd9f 8870e19991
commit cf68ce6681
13 changed files with 1135 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
doc/wiki/Community-collaboration.md Normal file
View File

@@ -0,0 +1,20 @@
This project is a community project
## Mailing list ##
- Google group: http://groups.google.com/group/eiffel-web-framework
## Materials ##
- wiki: github wiki at https://github.com/Eiffel-World/Eiffel-Web-Framework/wiki
- Shared documents: on google docs at http://goo.gl/M8WLP
- source code: git repository at https://github.com/Eiffel-World/Eiffel-Web-Framework
- Proposal from Paul Cohen for a EWSGI spec at http://eiffel.seibostudios.se/wiki/EWSGI
## Main contributors ##
- **jfiat**: Jocelyn Fiat (Eiffel Software | http://eiffel.com/)
- **jvelilla**: Hector Javier Velilla (Seibo Software Studios | http://http://seibostudios.se/en/)
- **paco**: Paul Cohen (Seibo Software Studios | http://http://seibostudios.se/en/)
- **daro**: Daniel Rodriguez (Seibo Software Studios | http://http://seibostudios.se/en/)
## You want to participate ##
- You are welcome to contribute (code, test, doc, code review, feedback, suggestion, spread the words ...)
- Feel free to subscribe to the mailing list

25
doc/wiki/EWSGI-Open-Questions.md Normal file
View File

@@ -0,0 +1,25 @@
## STRING_32, UTF-8, ... ? ##
Berend raised the point that using STRING_32 is consuming 4 times the space used for STRING_8.
And CPU is cheaper than memory, so we should try to use as less memory as possible.
And then for Berend, STRING_32 is not the solution.
Most of the data are just STRING_8 in CGI
so let's list the various request data
- **query_parameter** (from the query string ?foo=bar&extra=blabla )
in this case, I think the name can be url-encoded, and obviously the value too
I guess it makes sense to url-decode them
but on the other hand, we could just keep them url-encoded (as they are), and it is up to the application to url-decode them if needed.
Of course, we should provide facilities to url-decode those strings.
- **form_data_parameter** (from the POST method)
quite often, it is same kind of content that `parameters'
but .. here this might depends on the encoding for multi-parts encoding.
- **meta_variable** (from the request itself ... CGI meta variables..)
I am wondering about unicode domain name ...
- **input data** ...
I think this is up to the application
... to be continued ...

788
doc/wiki/EWSGI-specification.md Normal file
View File

@@ -0,0 +1,788 @@
**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.meta_variables' for the CGI meta variable
-- and `res' for the output buffer
require
res_status_unset: not res.status_is_set
deferred
ensure
res_status_set: res.status_is_set
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 WGI_VALUE
-- Environment variable related to `a_name'
require
a_name_valid: a_name /= Void and then not a_name.is_empty
deferred
end
meta_string_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
do
if attached meta_variable (a_name) as val then
Result := val.as_string
end
end
meta_variables: ITERABLE [WGI_VALUE]
-- These variables are specific to requests made with HTTP.
-- Interpretation of these variables may depend on the value of
-- SERVER_PROTOCOL.
--
-- Environment variables with names beginning with "HTTP_" contain
-- header data read from the client, if the protocol used was HTTP.
-- The HTTP header name is converted to upper case, has all
-- occurrences of "-" replaced with "_" and has "HTTP_" prepended to
-- give the environment variable name. The header data may be
-- presented as sent by the client, or may be rewritten in ways which
-- do not change its semantics. If multiple headers with the same
-- field-name are received then they must be rewritten as a single
-- header having the same semantics. Similarly, a header that is
-- received on more than one line must be merged onto a single line.
-- The server must, if necessary, change the representation of the
-- data (for example, the character set) to be appropriate for a CGI
-- environment variable.
--
-- The server is not required to create environment variables for all
-- the headers that it receives. In particular, it may remove any
-- headers carrying authentication information, such as
-- "Authorization"; it may remove headers whose value is available to
-- the script via other variables, such as "Content-Length" and
-- "Content-Type".
--
-- For convenience it might also include the following CGI entries
deferred
end
feature -- Common Gateway Interface - 1.1 8 January 1996
auth_type: detachable READABLE_STRING_32
-- This variable is specific to requests made via the "http"
-- scheme.
--
-- If the Script-URI required access authentication for external
-- access, then the server MUST set the value of this variable
-- from the 'auth-scheme' token in the request's "Authorization"
-- header field. Otherwise it is set to NULL.
--
-- AUTH_TYPE = "" | auth-scheme
-- auth-scheme = "Basic" | "Digest" | token
--
-- HTTP access authentication schemes are described in section 11
-- of the HTTP/1.1 specification [8]. The auth-scheme is not
-- case-sensitive.
--
-- Servers MUST provide this metavariable to scripts if the
-- request header included an "Authorization" field that was
-- authenticated.
deferred
end
content_length: detachable READABLE_STRING_32
-- This metavariable is set to the size of the message-body
-- entity attached to the request, if any, in decimal number of
-- octets. If no data are attached, then this metavariable is
-- either NULL or not defined. The syntax is the same as for the
-- HTTP "Content-Length" header field (section 14.14, HTTP/1.1
-- specification [8]).
--
-- CONTENT_LENGTH = "" | 1*digit
--
-- Servers MUST provide this metavariable to scripts if the
-- request was accompanied by a message-body entity.
deferred
end
content_length_value: NATURAL_64
-- Integer value related to `content_length"
deferred
end
content_type: detachable READABLE_STRING_32
-- If the request includes a message-body, CONTENT_TYPE is set to
-- the Internet Media Type [9] of the attached entity if the type
-- was provided via a "Content-type" field in the request header,
-- or if the server can determine it in the absence of a supplied
-- "Content-type" field. The syntax is the same as for the HTTP
-- "Content-Type" header field.
--
-- CONTENT_TYPE = "" | media-type
-- media-type = type "/" subtype *( ";" parameter)
-- type = token
-- subtype = token
-- parameter = attribute "=" value
-- attribute = token
-- value = token | quoted-string
--
-- The type, subtype, and parameter attribute names are not
-- case-sensitive. Parameter values MAY be case sensitive. Media
-- types and their use in HTTP are described in section 3.7 of
-- the HTTP/1.1 specification [8].
--
-- Example:
--
-- application/x-www-form-urlencoded
--
-- There is no default value for this variable. If and only if it
-- is unset, then the script MAY attempt to determine the media
-- type from the data received. If the type remains unknown, then
-- the script MAY choose to either assume a content-type of
-- application/octet-stream or reject the request with a 415
-- ("Unsupported Media Type") error. See section 7.2.1.3 for more
-- information about returning error status values.
--
-- Servers MUST provide this metavariable to scripts if a
-- "Content-Type" field was present in the original request
-- header. If the server receives a request with an attached
-- entity but no "Content-Type" header field, it MAY attempt to
-- determine the correct datatype, or it MAY omit this
-- metavariable when communicating the request information to the
-- script.
deferred
end
gateway_interface: READABLE_STRING_32
-- This metavariable is set to the dialect of CGI being used by
-- the server to communicate with the script. Syntax:
--
-- GATEWAY_INTERFACE = "CGI" "/" major "." minor
-- major = 1*digit
-- minor = 1*digit
--
-- Note that the major and minor numbers are treated as separate
-- integers and hence each may be more than a single digit. Thus
-- CGI/2.4 is a lower version than CGI/2.13 which in turn is
-- lower than CGI/12.3. Leading zeros in either the major or the
-- minor number MUST be ignored by scripts and SHOULD NOT be
-- generated by servers.
--
-- This document defines the 1.1 version of the CGI interface
-- ("CGI/1.1").
--
-- Servers MUST provide this metavariable to scripts.
--
-- The version of the CGI specification to which this server
-- complies. Syntax:
--
-- GATEWAY_INTERFACE = "CGI" "/" 1*digit "." 1*digit
--
-- Note that the major and minor numbers are treated as separate
-- integers and that each may be incremented higher than a single
-- digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in
-- turn is lower than CGI/12.3. Leading zeros must be ignored by
-- scripts and should never be generated by servers.
deferred
end
path_info: READABLE_STRING_32
-- The PATH_INFO metavariable specifies a path to be interpreted
-- by the CGI script. It identifies the resource or sub-resource
-- to be returned by the CGI script, and it is derived from the
-- portion of the URI path following the script name but
-- preceding any query data. The syntax and semantics are similar
-- to a decoded HTTP URL 'path' token (defined in RFC 2396 [4]),
-- with the exception that a PATH_INFO of "/" represents a single
-- void path segment.
--
-- PATH_INFO = "" | ( "/" path )
-- path = segment *( "/" segment )
-- segment = *pchar
-- pchar = <any CHAR except "/">
--
-- The PATH_INFO string is the trailing part of the <path>
-- component of the Script-URI (see section 3.2) that follows the
-- SCRIPT_NAME portion of the path.
--
-- Servers MAY impose their own restrictions and limitations on
-- what values they will accept for PATH_INFO, and MAY reject or
-- edit any values they consider objectionable before passing
-- them to the script.
--
-- Servers MUST make this URI component available to CGI scripts.
-- The PATH_INFO value is case-sensitive, and the server MUST
-- preserve the case of the PATH_INFO element of the URI when
-- making it available to scripts.
deferred
end
path_translated: detachable READABLE_STRING_32
-- PATH_TRANSLATED is derived by taking any path-info component
-- of the request URI (see section 6.1.6), decoding it (see
-- section 3.1), parsing it as a URI in its own right, and
-- performing any virtual-to-physical translation appropriate to
-- map it onto the server's document repository structure. If the
-- request URI includes no path-info component, the
-- PATH_TRANSLATED metavariable SHOULD NOT be defined.
--
--
-- PATH_TRANSLATED = *CHAR
--
-- For a request such as the following:
--
-- http://somehost.com/cgi-bin/somescript/this%2eis%2epath%2einfo
--
-- the PATH_INFO component would be decoded, and the result
-- parsed as though it were a request for the following:
--
-- http://somehost.com/this.is.the.path.info
--
-- This would then be translated to a location in the server's
-- document repository, perhaps a filesystem path something like
-- this:
--
-- /usr/local/www/htdocs/this.is.the.path.info
--
-- The result of the translation is the value of PATH_TRANSLATED.
--
-- The value of PATH_TRANSLATED may or may not map to a valid
-- repository location. Servers MUST preserve the case of the
-- path-info segment if and only if the underlying repository
-- supports case-sensitive names. If the repository is only
-- case-aware, case-preserving, or case-blind with regard to
-- document names, servers are not required to preserve the case
-- of the original segment through the translation.
--
-- The translation algorithm the server uses to derive
-- PATH_TRANSLATED is implementation defined; CGI scripts which
-- use this variable may suffer limited portability.
--
-- Servers SHOULD provide this metavariable to scripts if and
-- only if the request URI includes a path-info component.
deferred
end
query_string: READABLE_STRING_32
-- A URL-encoded string; the <query> part of the Script-URI. (See
-- section 3.2.)
--
-- QUERY_STRING = query-string
-- query-string = *uric
-- The URL syntax for a query string is described in section 3 of
-- RFC 2396 [4].
--
-- Servers MUST supply this value to scripts. The QUERY_STRING
-- value is case-sensitive. If the Script-URI does not include a
-- query component, the QUERY_STRING metavariable MUST be defined
-- as an empty string ("").
deferred
end
remote_addr: READABLE_STRING_32
-- The IP address of the client sending the request to the
-- server. This is not necessarily that of the user agent (such
-- as if the request came through a proxy).
--
-- REMOTE_ADDR = hostnumber
-- hostnumber = ipv4-address | ipv6-address
-- The definitions of ipv4-address and ipv6-address are provided
-- in Appendix B of RFC 2373 [13].
--
-- Servers MUST supply this value to scripts.
deferred
end
remote_host: detachable READABLE_STRING_32
-- The fully qualified domain name of the client sending the
-- request to the server, if available, otherwise NULL. (See
-- section 6.1.9.) Fully qualified domain names take the form as
-- described in section 3.5 of RFC 1034 [10] and section 2.1 of
-- RFC 1123 [5]. Domain names are not case sensitive.
--
-- Servers SHOULD provide this information to scripts.
deferred
end
remote_ident: detachable READABLE_STRING_32
-- The identity information reported about the connection by a
-- RFC 1413 [11] request to the remote agent, if available.
-- Servers MAY choose not to support this feature, or not to
-- request the data for efficiency reasons.
--
-- REMOTE_IDENT = *CHAR
--
-- The data returned may be used for authentication purposes, but
-- the level of trust reposed in them should be minimal.
--
-- Servers MAY supply this information to scripts if the RFC1413
-- [11] lookup is performed.
deferred
end
remote_user: detachable READABLE_STRING_32
-- If the request required authentication using the "Basic"
-- mechanism (i.e., the AUTH_TYPE metavariable is set to
-- "Basic"), then the value of the REMOTE_USER metavariable is
-- set to the user-ID supplied. In all other cases the value of
-- this metavariable is undefined.
--
-- REMOTE_USER = *OCTET
--
-- This variable is specific to requests made via the HTTP
-- protocol.
--
-- Servers SHOULD provide this metavariable to scripts.
deferred
end
request_method: READABLE_STRING_32
-- The REQUEST_METHOD metavariable is set to the method with
-- which the request was made, as described in section 5.1.1 of
-- the HTTP/1.0 specification [3] and section 5.1.1 of the
-- HTTP/1.1 specification [8].
--
-- REQUEST_METHOD = http-method
-- http-method = "GET" | "HEAD" | "POST" | "PUT" | "DELETE"
-- | "OPTIONS" | "TRACE" | extension-method
-- extension-method = token
--
-- The method is case sensitive. CGI/1.1 servers MAY choose to
-- process some methods directly rather than passing them to
-- scripts.
--
-- This variable is specific to requests made with HTTP.
--
-- Servers MUST provide this metavariable to scripts.
deferred
end
script_name: READABLE_STRING_32
-- The SCRIPT_NAME metavariable is set to a URL path that could
-- identify the CGI script (rather than the script's output). The
-- syntax and semantics are identical to a decoded HTTP URL
-- 'path' token (see RFC 2396 [4]).
--
-- SCRIPT_NAME = "" | ( "/" [ path ] )
--
-- The SCRIPT_NAME string is some leading part of the <path>
-- component of the Script-URI derived in some implementation
-- defined manner. No PATH_INFO or QUERY_STRING segments (see
-- sections 6.1.6 and 6.1.8) are included in the SCRIPT_NAME
-- value.
--
-- Servers MUST provide this metavariable to scripts.
deferred
end
server_name: READABLE_STRING_32
-- The SERVER_NAME metavariable is set to the name of the server,
-- as derived from the <host> part of the Script-URI (see section
-- 3.2).
--
-- SERVER_NAME = hostname | hostnumber
--
-- Servers MUST provide this metavariable to scripts.
deferred
end
server_port: INTEGER_32
-- The SERVER_PORT metavariable is set to the port on which the
-- request was received, as used in the <port> part of the
-- Script-URI.
--
-- SERVER_PORT = 1*digit
--
-- If the <port> portion of the script-URI is blank, the actual
-- port number upon which the request was received MUST be
-- supplied.
--
-- Servers MUST provide this metavariable to scripts.
deferred
end
server_protocol: READABLE_STRING_32
-- The SERVER_PROTOCOL metavariable is set to the name and
-- revision of the information protocol with which the request
-- arrived. This is not necessarily the same as the protocol
-- version used by the server in its response to the client.
--
-- SERVER_PROTOCOL = HTTP-Version | extension-version
-- | extension-token
-- HTTP-Version = "HTTP" "/" 1*digit "." 1*digit
-- extension-version = protocol "/" 1*digit "." 1*digit
-- protocol = 1*( alpha | digit | "+" | "-" | "." )
-- extension-token = token
--
-- 'protocol' is a version of the <scheme> part of the
-- Script-URI, but is not identical to it. For example, the
-- scheme of a request may be "https" while the protocol remains
-- "http". The protocol is not case sensitive, but by convention,
-- 'protocol' is in upper case.
--
-- A well-known extension token value is "INCLUDED", which
-- signals that the current document is being included as part of
-- a composite document, rather than being the direct target of
-- the client request.
--
-- Servers MUST provide this metavariable to scripts.
deferred
end
server_software: READABLE_STRING_32
-- The SERVER_SOFTWARE metavariable is set to the name and
-- version of the information server software answering the
-- request (and running the gateway).
--
-- SERVER_SOFTWARE = 1*product
-- product = token [ "/" product-version ]
-- product-version = token
-- Servers MUST provide this metavariable to scripts.
deferred
end
feature -- HTTP_*
http_accept: detachable READABLE_STRING_32
-- Contents of the Accept: header from the current request, if there is one.
-- Example: 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'
deferred
end
http_accept_charset: detachable READABLE_STRING_32
-- Contents of the Accept-Charset: header from the current request, if there is one.
-- Example: 'iso-8859-1,*,utf-8'.
deferred
end
http_accept_encoding: detachable READABLE_STRING_32
-- Contents of the Accept-Encoding: header from the current request, if there is one.
-- Example: 'gzip'.
deferred
end
http_accept_language: detachable READABLE_STRING_32
-- Contents of the Accept-Language: header from the current request, if there is one.
-- Example: 'en'.
deferred
end
http_connection: detachable READABLE_STRING_32
-- Contents of the Connection: header from the current request, if there is one.
-- Example: 'Keep-Alive'.
deferred
end
http_host: detachable READABLE_STRING_32
-- Contents of the Host: header from the current request, if there is one.
deferred
end
http_referer: detachable READABLE_STRING_32
-- The address of the page (if any) which referred the user agent to the current page.
-- This is set by the user agent.
-- Not all user agents will set this, and some provide the ability to modify HTTP_REFERER as a feature.
-- In short, it cannot really be trusted.
deferred
end
http_user_agent: detachable READABLE_STRING_32
-- Contents of the User-Agent: header from the current request, if there is one.
-- This is a string denoting the user agent being which is accessing the page.
-- A typical example is: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586).
-- Among other things, you can use this value to tailor your page's
-- output to the capabilities of the user agent.
deferred
end
http_authorization: detachable READABLE_STRING_32
-- Contents of the Authorization: header from the current request, if there is one.
deferred
end
feature -- Extra CGI environment variables
request_uri: READABLE_STRING_32
-- The URI which was given in order to access this page; for instance, '/index.html'.
deferred
end
orig_path_info: detachable READABLE_STRING_32
-- Original version of path_info before processed by Current environment
deferred
end
feature -- Query string Parameters
query_parameters: ITERABLE [WGI_VALUE]
-- Variables extracted from QUERY_STRING
deferred
end
query_parameter (a_name: READABLE_STRING_GENERAL): detachable WGI_VALUE
-- 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: ITERABLE [WGI_VALUE]
-- Variables sent by POST request
deferred
end
form_data_parameter (a_name: READABLE_STRING_GENERAL): detachable WGI_VALUE
-- 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
deferred
end
feature -- Cookies
cookies: ITERABLE [WGI_VALUE]
-- Expanded cookies variable
deferred
end
cookie (a_name: READABLE_STRING_GENERAL): detachable WGI_VALUE
-- Field for name `a_name'.
require
a_name_valid: a_name /= Void and then not a_name.is_empty
deferred
end
feature -- Access: all variables
items: ITERABLE [WGI_VALUE]
-- 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
item (a_name: READABLE_STRING_GENERAL): detachable WGI_VALUE
-- 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: READABLE_STRING_GENERAL): 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
invariant
server_name_not_empty: not server_name.is_empty
server_port_set: server_port /= 0
request_method_attached: request_method /= Void
path_info_attached: path_info /= Void
query_string_attached: query_string /= Void
remote_addr_attached: remote_addr /= Void
same_orig_path_info: orig_path_info ~ meta_string_variable ({WGI_META_NAMES}.orig_path_info)
same_path_info: path_info ~ meta_string_variable ({WGI_META_NAMES}.path_info)
path_info_identical: path_info ~ meta_string_variable ({WGI_META_NAMES}.path_info)
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: READABLE_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)
-- 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: READABLE_STRING_8)
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: READABLE_STRING_8; value: READABLE_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
message_writable: message_writable
end
feature -- Output operation
write_string (s: READABLE_STRING_8)
-- Send the string `s'
require
message_writable: message_writable
deferred
end
write_substring (s: READABLE_STRING_8; 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: READABLE_STRING_8)
-- 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

105
doc/wiki/EWSGI-specification:-difference-in-main-proposals.md Normal file
View File

@@ -0,0 +1,105 @@
Currently the **design of the EWSGI** is not going very fast, mainly due to conflicts for the core design.
Let's try to summary today's **points of conflict** between Paul's proposal, and Jocelyn's proposal.
Since Paul put the specification on the wiki from Seibo Solution Studio,
and Jocelyn is implementing the proposal withing the current Eiffel Web Framework.
(If other proposals are provided, we'll compare them to those 2 existing proposals.)
Let's name the **Seibo-EWSGI** proposal and the **EWF-EWSGI** proposal.
Of course, **the goal is to have only one specification**, but it is good to have more than one proposal. So that we really try to specify the best EWSGI as possible.
Let's remind that EWSGI is meant to be a specification, and we are looking at **Specification-Compliance** for the future implementation (so this is mainly about class names, and feature signatures. I.e the Eiffel system interface).
_Note_: to make the code shorter, we will not always include the prefix EWSGI_ to the class name.
_Note2_: we will use the term of "user" for the developer using the EWSGI specification and/or implementation(s)
## General goal ##
At first, the main difference between Seibo-EWSGI and EWF-EWSGI is a tiny nuance on the general goal.
_Seibo-EWSGI_: get web application portability across a variety of web servers.
_EWF-EWSGI_: get web application portability across a variety of web servers including connectors.
Both are following the CGI specification.
To resume, the goal is to get an Eiffel Web ecosystem based on EWSGI specification which allow to write components, libraries, applications based on EWSGI, and which can be compiled and used without changes on the various EWSGI implementations.
EWF-EWSGI is also targetting to make the connector implementations portable on the various EWSGI implementation. However this is not the most critical point, and could be address in later specification version, or maybe a specific EWSGI/Connector specification ...
**Conclusion**: the general goal is (merely) the same for both proposals.
That is a good point, otherwise no need to compare the 2 proposals
## Main entry point for a Web application component ##
This is the first important difference in the class EWSGI_APPLICATION
Seibo-EWSGI:
response (request: EWSGI_REQUEST): EWSGI_RESPONSE is
-- The response to the given 'request'.
deferred
ensure
Result.status_is_set
Result.ready_to_transmit
end
EWF-EWSGI:
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
end
So the main difference is for the user/developer
Seibo-EWSGI: the user has to create the RESPONSE object.
EWF-EWSGI: the user has the RESPONSE_BUFFER object passed as argument, and it is ready to use.
The consequences are important because
* Seibo-EWSGI:
- to make the creation of RESPONSE simple, the decision was to remove any notion of output stream in EWSGI.
- Then the RESPONSE has to be built before sending it. But the proposal also provides a way to get the response message by block during the transmission. A kind of delay RESPONSE filling which is for now using a read_block pattern. And this mimics the send immediately the message parts to the client.
- This design allows the developer to use its own descendant of RESPONSE and then implement the "read_block" pattern when needed.
- This also allows to control carefully that the status+headers are sent before the body. And if not using the read_block pattern, this allows to set/change the headers even after setting the message body, in fact you really build the Response as an object, and you set the various attributes whenever you want.
- The read_block pattern is meant to address the case where the message would be too big to stay in memory, and/or to send some part immediately to the client, but for that you must stick to the read_block pattern.
- Seibo team find the Response-as-Result design more natural, and adopt the Request/Response model of HTTP protocol
* EWF-EWSGI:
- the RESPONSE_BUFFER is passed by argument to the user, then he does not have to worry about how to create it.
- it is a buffer and could be implemented in various way by the implementation(s) to access the output stream if any
- For now, there is no easy way for the user, from the proposed specification, to have a customized RESPONSE_BUFFER
- It is easy to implement the Seibo-EWSGI design on top of EWF-EWSGI (the code is provided in EWF-ewsgi implementation)
- the buffer specification allows the user to send the message parts immediately to the client without complicated pattern. As today implementation, the only restriction imposed by the design is to pass the Status code, and the headers before starting sending the message parts; this is checked by the associated assertions. However this part might be thinked again, to be more flexible, and let this to the responsibility of the user, or of other frameworks built on top of EWSGI spec.
## Notion of output stream ##
As you might noticed
In EWF-EWSGI, the output stream is kind of hidden and replaced by the output buffer, which is in fact quite similar. However the goal is to allow the user to send immediately the message parts to the client as simple as writing in the buffer.
The EWSGI implementation will handle this buffer to integrate nicely with the underlying web server techno. This will be done through the implementation of the various connectors.
In Seibo-EWSGI there is NO notion of output stream, this is to handle the potential case of a HTTP server technologies following CGI specification but without any output stream.
The read_block pattern allows the user to send a big response part by part, and/or also send some message parts immediately to the client during the transmission, this looks like a delayed computation of the messages.
---
So for now, those are the main critical (blocking) differences I (Jocelyn) can see.
## Personal point of views ##
(Feel free to add your own point of view)
### Jocelyn ###
* I prefer the EWF-EWSGI solution (obviously this is my proposal) mainly because with it, you can also implement the Seibo-EWSGI design. And the "more you can do, the less you can also do".
* I find the read_block pattern really not natural to use in non trivial application (even in trivial application, this might not be that easy to handle, and thus a potential source of bugs)
* I admit the need to send immediately to the client might not be the vast majority of cases. But this is useful for big messages, and for long computing message where the client wants to follow the progression (concrete cases: drupal batch, wordpress online update, ...)
* I would prefer to include the connector part into the EWSGI specification, this way any EWSGI_connector implementation could work with any EWSGI implementation. Otherwise we might end up with many different EWSGI implementations, and according to the underlying connector(s) you want to use, you will need to use different EWSGI implementations.
### Others ... ? ###
Please contribute ... correct also the wiki page if there are mistake or misunderstanding.

72
doc/wiki/EWSGI.md Normal file
View File

@@ -0,0 +1,72 @@
- See proposed specifications: [[EWSGI specification| EWSGI-specification]]
- See [[Open questions| EWSGI-open-questions]]
- And below the various proposals and associated decision
----
# Waiting for decision
## Include EWF_HEADER into EWSGI as WGI_HEADERS
- Code: **P-2011-09-26-include-wgi-headers**
- Status: proposed on 2011-09-26 **WAITING FOR APPROVAL**
> Include WGI_HEADERS to help the user to build HTTP Header.
> So that he doesn't have to know the HTTP specification for usual needs
----
# Adopted entries
## Rename `parameter` into `item`
- Code: **P-2011-09-07-renaming_REQUEST_item**
- Status: proposed on 2011-09-07 **ADOPTED-by-default**
> rename `{REQUEST}.parameter (n: READABLE_STRING_GENERAL): detachable WGI_VALUE`
> into `{REQUEST}.item (n: READABLE_STRING_GENERAL): detachable WGI_VALUE`
> and similar for `parameters` -> `items`
## Return type of `parameter' (and similar query_, form_data_ ...) should be deferred WGI_VALUE
- Code: **P-2011-09-05-WGI_VALUE**
- Status: proposed on 2011-09-05 **ADOPTED-by-default**
> Instead of returning just `READABLE_STRING_32` , it would be better to use **WGI_VALUE** .
> Mainly to address the multiple value for the same param name, but also for uploaded files.
> This allows to have various types such as WGI_STRING_VALUE, WGI_LIST_VALUE, WGI_TABLE_VALUE, WGI_FILE_VALUE .
>
> Thus we would have: <code>parameter (a_name: READABLE_STRING_GENERAL): detachable WGI_VALUE </code>
## Include the parameter's name in WGI_VALUE interface
- Code: **P-2011-09-05-WGI_VALUE_interface**
- Dependence: adoption of P-2011-09-05-WGI_VALUE , may impact on P-2011-09-05-parameters_ITERABLE
- Status: proposed on 2011-09-05 **ADOPTED-by-default**
> include the corresponding parameter's name in WGI_VALUE interface.
> Such as `{WGI_VALUE}.name: READABLE_STRING_GENERAL` (or READABLE_STRING_32).
>
> This would also allow to replace
> signature `parameters: ITERABLE [TUPLE [name: READABLE_STRING_GENERAL; value: WGI__VALUE]]'
> by a nicer signature `parameters: ITERABLE [WGI__VALUE]`
## Signature of parameters (and similar) using ITERABLE [...]
- Code: **P-2011-09-05-parameters_ITERABLE**
- Status: proposed on 2011-09-05 **ADOPTED-by-default**
> Description: Instead of forcing the implementation to use HASH_TABLE, DS_HASH_TABLE, DS_HASH_SET, ... or similar
> we should use `ITERABLE`
>
> `parameters: ITERABLE [TUPLE [name: READABLE_STRING_GENERAL; value: WGI_VALUE]]`
>
> Or, if `P-2011-09-05-WGI_VALUE_interface` is adopted (WGI_VALUE.name holds the related parameter's name)
>
> `parameters: ITERABLE [WGI_VALUE]`
## Change prefix from EWSGI_ to WGI_
- Code: **P-2011-08-29-WGI_prefix**
- Status: **adopted**
- Decision: **WGI_**
> shorter and pronouncable prefix for EWSGI class names
----
# Rejected entries
...

21
doc/wiki/HTTP-client-library.md Normal file
View File

@@ -0,0 +1,21 @@
# HTTP Library Features
The following list of features are taken form the book [RESTful Web Services](http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260/ref=sr_1_1?ie=UTF8&qid=1322155984&sr=8-1)
* **HTTPS**: _It must support HTTPS and SSL certificate validation_
* **HTTP methods**: _It must support at least the five main HTTP methods: GET, HEAD, POST, PUT, and DELETE. Optional methods
OPTIONS and TRACE, and WebDAV extensions like MOVE, ._
* **Custom data** : _It must allow the programmer to customize the data sent as the entity-body of a
PUT or POST request._
* **Custom headers** : _It must allow the programmer to customize a request’s HTTP headers_
* **Response Codes** : _It must give the programmer access to the response code and headers of an HTTP
response; not just access to the entity-body._
* **Proxies**: _It must be able to communicate through an HTTP proxy_
* **Compression**:_it should automatically request data in compressed form to save
bandwidth, and transparently decompress the data it receives._
* **Caching**:_It should automatically cache the responses to your requests._
* **Auth methods** : _It should transparently support the most common forms of HTTP authentication:
Basic, Digest, and WSSE._
* **Cookies** :_It should be able to parse and create HTTP cookie strings_
* **Redirects**:_It should be able to transparently follow HTTP redirects_

14
doc/wiki/Home.md Normal file
View File

@@ -0,0 +1,14 @@
## Eiffel-Web-Framework ##
The official documentation/wiki is located at https://github.com/EiffelWebFramework/EWF/wiki , if you are visiting a "clone/fork", please always check the [[official wiki|https://github.com/EiffelWebFramework/EWF/wiki]].
- Mailing list: please visit and subscribe to the mailing list page [[http://groups.google.com/group/eiffel-web-framework]] ![logo](http://groups.google.com/intl/en/images/logos/groups_logo_sm.gif)
- See also
- You want to contribute or follow the progress/discussion, see the [[collaboration page| Community-collaboration]]
- [[list of tasks, and a potential roadmap| Tasks-Roadmap]]
- [[General source structure of this project| Source-structure]]
- EWSGI: [[Eiffel Web Server Gateway Interface| EWSGI]]
- [[Overview of the server side architecture| Spec-Server-Architecture]]
- This project is also a collection of [[Libraries]] related to the Web

15
doc/wiki/Libraries.md Normal file
View File

@@ -0,0 +1,15 @@
## libraries currently part of the Eiffel Web Framework ##
* [[Library-EWSGI]]: Eiffel Web Server Gateway Interface (prefix WGI_ for **W**eb**G**ateway**I**nterface)
* [[Library-libFCGI]]: Eiffel wrapper of libfcgi SDK (http://www.fastcgi.com/devkit/libfcgi/)
* [[Library-encoder]]: simple encoder for base64, url-encode, xml entities
* [[Library-error]]: simple framework to handle error in EWSGI and related
* [[Library-http]]: utility classes to handle HTTP protocol, status, ...
* [[Library-uri-template]]: URI Template parser and expander (follow draft spec 0.5)
## libraries needed but not (yet) in the current framework ##
* [[Library-EiffelWebNino]]: Eiffel Web Server written in Eiffel
* [[Library-JSON]]: JSON format parser and converter
## libraries that could be included, or or used ##
* eMIME: MIME parser, and encoder ...
* ...

28
doc/wiki/Source-structure.md Normal file
View File

@@ -0,0 +1,28 @@
## Currently ##
- LICENSE : file containing the global license
- README : quick README to point to the github project
- doc/
- doc/wiki : clone of the associated github wiki repository
- examples/
- tests/
- library/
- library/server/ewsgi/ewsgi.ecf
- library/server/ewsgi/ewsgi.ecf
Any library/component (in development mode) should follow the following structure (when not needed, there is no need to create the associated folder(s) ):
- **README**
- **COPYRIGHT**
- **LICENSE**
- **.ecf** and **-safe.ecf** : configuration file
- **library/** : the place to put the source code of the related library/component
- **doc/** : notes, documentations, ...
- **tests/** : standard place to put your tests, if you are using Eiffel Software auto-tests, I would suggest to add a new target into the associated .ecf (instead of building a new .ecf under test/ )
- **examples/** : standard place to put the example
- **build/** : a convenient place to compile your project, using this convention, you can setup utilities such as backup to ignore this folder.
- **resources/** : contains pixmap files, ....
- **install/** : contains installation scripts for each platform
- **data/** : contains eventual data for the related tools
See that we use the singular, since it is an Eiffel convention for naming cluster or folder.

3
doc/wiki/Spec-server-architecture.md Normal file
View File

@@ -0,0 +1,3 @@
## Diagram: Overview of the server architecture ##
![server_architecture.png](server_architecture.png)

10
doc/wiki/Task-json.md Normal file
View File

@@ -0,0 +1,10 @@
## Goal ##
- Make this JSON library the default one for the community
## Steps ##
- restructure to follow the (doc,library,test,...) structure
- extract gobo from it, and provide json.ecf, json-safe.ecf, json_with_gobo.ecf (and json_with_gobo-safe.ecf : not possible right now, but we can _cheat_)
- and then let Eiffel Software include it, in the official libraries
## Roadmap ##
- this should be done before 1st of October

34
doc/wiki/Tasks-Roadmap.md Normal file
View File

@@ -0,0 +1,34 @@
## October 1st ##
* Source code , layout/handling EWR (**jfiat**)
* "Eiffel WSGI" spec (github wiki) (**paco**)
* Eiffel Web Nino (**jvelilla**)
* REST component (**jfiat**)
* Example/reference Eiffel Web Server App (**jvelilla**)
- Hello World
- Restbucks (from the book REST in Practice)
* WAMIE/apache based support for Eiffel WSGI (**daro**)
- SCOOP ...
* Some persistance solution (**daro**)
* XML, [[JSON|Task-JSON]] support (**jvelilla**)
## Maybe for October 1st ##
* Reference Client/REST-service consumer (**jfiat**)
* Mashup support, facebook, twitter, google+, ... (**jfiat**)
* Authentication support (**jfiat** ?)
- OpenID, Google Connect, Facebook Connect, OAuth, ...
- http authorization
## December ##
* Session handling
- Cookie based
- REST-based session example
* Access Control
* Application builder
- Deployment
- Persistence chooser
* Dynamic update of running system (**daro**)
## Contributors ##
- See [[the collaboration page|Community-collaboration]]
note: In bold, you see the responsible for each task, but contribution from other is possible as well.

BIN
doc/wiki/server_architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB