From 0744e131321691c83184dc2e7fce0fcb2a113519 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:04:19 -0800 Subject: [PATCH 01/21] draft --- Documentation.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 Documentation.md diff --git a/Documentation.md b/Documentation.md new file mode 100644 index 00000000..ff452281 --- /dev/null +++ b/Documentation.md @@ -0,0 +1,180 @@ +# Current Status +* Official repository: +* Official website: + +# What is EWF? + +Eiffel Web Framework, is mainly a collection of Eiffel libraries designed to be integrated with each other. One benefit is that it supports all core HTTP features, so enable you embrace HTTP as an application protocol to develop web applications. So you do not need to adapt your applications to the web, instead you use the web power. It means you can build different kind of web applications, from Web APIs following the Hypermedia API style (REST style), CRUD web services or just conventional web applications building a session on top of an stateless protocol. + +# EWF core/kernel +_The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_)._ + +To build a web [service](./Documentation#service), the framework provides a set of core components to launch the service, for each [#request request], access the data, and send the [[Documentation #response|response]]. +The framework also provides a router component to help dispatching the incoming request. + +A service can be a web api, a web interface, … what ever run on top of HTTP. + +# Service +see interface: WSF_SERVICE + +Each incoming http request is processed by the following routine. + +{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE) + +This is the low level of the framework, at this point, `req’ provides access to the query and form parameters, input data, headers, … as specified by the Common Gateway Interface (CGI). +The response `res’ is the interface to send data back to the client. +For convenience, the framework provides richer service interface that handles the most common needs (filter, router, …). + +# Request and Response +see interface: WSF_REQUEST and WSF_RESPONSE +Any incoming http request is represented by an new object of type WSF_REQUEST. +WSF_REQUEST provides access to +meta variables: CGI variables (coming from the request http header) +query parameters: from the uri ex: ?q=abc&type=pdf +input data: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. +form parameters: standard parameters from the request input data. +typically available when a web form is sent using POST as content of type multipart/form-data or application/x-www-form-urlencoded +(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) +uploaded files: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. +cookies variable: cookies extracted from the http header. +path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) +execution variables: used by the application to keep value associated with the request. + +The WSF_RESPONSE represents the communication toward the client, a service need to provide correct headers, and content. For instance the Content-Type, and Content-Length. It also allows to send data with chunked encoding. + +{{Learn more}} +Connectors: +see WGI_CONNECTOR +Using EWF, your service is built on top of underlying httpd solution/connectors. +Currently 3 main connectors are availables: +CGI: following the CGI interface, this is an easy solution to run the service on any platform. +libFCGI: based on the libfcgi solution, this can be used with apache, IIS, nginx, … +nino: a standalone server: Eiffel Web Nino allow you to embed a web server anywhere, on any platform without any dependencies on other httpd server. +At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. +It is fairly easy to add new connector, it just has to follow the EWSGI interface +Router or Request Dispatcher: +Routes HTTP requests to the proper execution code +A web application needs to have a clean and elegant URL scheme, and EWF provides a router component to design URLs. + +The association between a URL pattern and the code handling the URL request is called a Router mapping in EWF. + +EWF provides 3 main kinds of mappings +URI: any URL with path being the specified uri. +example: “/users/” redirects any “/users/” and “/users/?query=...” +URI-template: any URL matching the specified URI-template +example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” +Starts-with: any URL starting with the specified path +Note: in the future, a Regular-Expression based kind will be added in the future, and it is possible to use custom mapping on top of EWF. + +Code: +router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( +“/project/{name}”, project_handler) +) + -- And precising the request methods +router.map_with_request_methods ( … , router.methods_GET_POST) + + +In the previous code, the `project_handler’ is an object conforming to WSF_HANDLER, that will process the incoming requests matching URI-template “/project/{name}”. + +Usually, the service will inherit from WSF_ROUTED_SERVICE, which has a `router’ attribute. +Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_router’. + +To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map’ URI template with agent, and so on. +See +map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) +map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]]) +and same with request methodes … +… +Check WSF_*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. + + + + +How we do that in EWF? : Router with (or without context). +Related code: wsf_router, wsf_router_context +Examples + +EWF components +URI Handler: + Parses the details of the URI (scheme, path, query info, etc.) and exposes them for use. +How we do that in EWF?: URI Templates, but we could also use regex. +Related code: uri_template +Examples: + + +Mime Parser/ Content Negotiation: +Handles the details of determining the media type, language, encoding, compression (conneg). +How do we do that in EWF? Content_Negotiation library. +Example + + +Request Handler +target of request dispatcher + uri handler. +Here is where we handle GET, POST PUT, etc. + +Representation Mapping +Converts stored data into the proper representation for responses and handles incoming representations from requests. + +We don’t have a representation library, the developer need to do that. +If we want to provide different kind of representations: JSON, XML, HTML, the responsibility is let +to the developer to map their domain to the target representation. + +Http Client: + A simple library to make requests and handle responses from other http servers. +How we do that in EWF? http client library +examples: + +Authentication/Security: + Handle differents auth models. (Basic, Digest?, OAuth, OpenId) +How we do that in EWF? http_authorization, OpenId, and Cypress +examples. + +Caching: + Support for Caching and conditional request +How we do that in Eiffel? Policy framework on top of EWF. {{{need_review}}} +examples + + + + +EWF HTML5 Widgets + +EWF policy Framework + +EWF application generators + + + +Specification +EWSGI + + + +Libraries + +I’m including external libraries, like Cypress OAuth (Security), HTML parsing library, Template Engine Smarty. + + +server +ewsgi: Eiffel Web Server Gateway Interface read more +connectors: various web server connectors for EWSGI +libfcgi: Wrapper for libfcgi SDK +wsf: Web Server Framework read more +router: URL dispatching/routing based on uri, uri_template, or custom read more +wsf_html: (html and css) Content generator from the server side. +CMS example: https://github.com/EiffelWebFramework/cms/tree/master/example +protocol +http: HTTP related classes, constants for status code, content types, ... read more +uri_template: URI Template library (parsing and expander) read more +content_negotiation: CONNEG library (Content-type Negociation) read more +Client +http_client: simple HTTP client based on cURL readmore +Firebase API: https://github.com/EiffelWebFramework/Redwood +Text +encoder: Various simpler encoders: base64, url-encoder, xml entities, html entities read more +Utils +error: very simple/basic library to handle error +Security +http_authentication (under EWF/library/server/authentication) +open_id (under EWF/library/security) +OAuth (https://github.com/EiffelWebFramework/cypress) From 45cd633e12e190a4cf48a0edc1b79461d77b50b8 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:10:50 -0800 Subject: [PATCH 02/21] Updated Documentation (markdown) --- Documentation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation.md b/Documentation.md index ff452281..de10d585 100644 --- a/Documentation.md +++ b/Documentation.md @@ -7,19 +7,19 @@ Eiffel Web Framework, is mainly a collection of Eiffel libraries designed to be integrated with each other. One benefit is that it supports all core HTTP features, so enable you embrace HTTP as an application protocol to develop web applications. So you do not need to adapt your applications to the web, instead you use the web power. It means you can build different kind of web applications, from Web APIs following the Hypermedia API style (REST style), CRUD web services or just conventional web applications building a session on top of an stateless protocol. # EWF core/kernel -_The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_)._ +_ The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_). _ -To build a web [service](./Documentation#service), the framework provides a set of core components to launch the service, for each [#request request], access the data, and send the [[Documentation #response|response]]. -The framework also provides a router component to help dispatching the incoming request. +To build a web [service](#service), the framework provides a set of core components to launch the service, for each [request](#request-and-response), access the data, and send the [response](#request-and-response). +The framework also provides a router component to help dispatching the incoming request. A service can be a web api, a web interface, … what ever run on top of HTTP. # Service -see interface: WSF_SERVICE +_ see interface: WSF_SERVICE _ Each incoming http request is processed by the following routine. -{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE) +`{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` This is the low level of the framework, at this point, `req’ provides access to the query and form parameters, input data, headers, … as specified by the Common Gateway Interface (CGI). The response `res’ is the interface to send data back to the client. From 8bd14f5f212239e96bef09e0c9d71cd7d2137d83 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:13:06 -0800 Subject: [PATCH 03/21] Updated Documentation (markdown) --- Documentation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation.md b/Documentation.md index de10d585..b8bc9848 100644 --- a/Documentation.md +++ b/Documentation.md @@ -14,6 +14,7 @@ The framework also provides a router component to help dispatching the incoming A service can be a web api, a web interface, … what ever run on top of HTTP. + # Service _ see interface: WSF_SERVICE _ From c7668810527857c4a3fc0e8f5d68935f5c3d00bb Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:17:15 -0800 Subject: [PATCH 04/21] Updated Documentation (markdown) --- Documentation.md | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/Documentation.md b/Documentation.md index b8bc9848..f8992f4c 100644 --- a/Documentation.md +++ b/Documentation.md @@ -16,36 +16,40 @@ A service can be a web api, a web interface, … what ever run on top of HTTP. # Service -_ see interface: WSF_SERVICE _ +_ see interface: **WSF_SERVICE** _ Each incoming http request is processed by the following routine. -`{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` +> `{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` This is the low level of the framework, at this point, `req’ provides access to the query and form parameters, input data, headers, … as specified by the Common Gateway Interface (CGI). The response `res’ is the interface to send data back to the client. For convenience, the framework provides richer service interface that handles the most common needs (filter, router, …). + # Request and Response -see interface: WSF_REQUEST and WSF_RESPONSE -Any incoming http request is represented by an new object of type WSF_REQUEST. -WSF_REQUEST provides access to -meta variables: CGI variables (coming from the request http header) -query parameters: from the uri ex: ?q=abc&type=pdf -input data: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. -form parameters: standard parameters from the request input data. -typically available when a web form is sent using POST as content of type multipart/form-data or application/x-www-form-urlencoded -(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) -uploaded files: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. -cookies variable: cookies extracted from the http header. -path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) -execution variables: used by the application to keep value associated with the request. +_ see interface: **WSF_REQUEST** and **WSF_RESPONSE** _ +Any incoming http request is represented by an new object of type **WSF_REQUEST**. -The WSF_RESPONSE represents the communication toward the client, a service need to provide correct headers, and content. For instance the Content-Type, and Content-Length. It also allows to send data with chunked encoding. +**WSF_REQUEST** provides access to +* meta variables: CGI variables (coming from the request http header) +* query parameters: from the uri ex: ?q=abc&type=pdf +* input data: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. +* form parameters: standard parameters from the request input data. + *typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` + *(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) +* uploaded files: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. +* cookies variable: cookies extracted from the http header. +* path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) +* execution variables: used by the application to keep value associated with the request. + +The **WSF_RESPONSE** represents the communication toward the client, a service need to provide correct headers, and content. For instance the `Content-Type`, and `Content-Length`. It also allows to send data with chunked encoding. {{Learn more}} -Connectors: -see WGI_CONNECTOR + + +# Connectors: +_see **WGI_CONNECTOR**_ Using EWF, your service is built on top of underlying httpd solution/connectors. Currently 3 main connectors are availables: CGI: following the CGI interface, this is an easy solution to run the service on any platform. From 73ce700eceb583d3105554bbde9a7485e2e57330 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:17:44 -0800 Subject: [PATCH 05/21] Updated Documentation (markdown) --- Documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation.md b/Documentation.md index f8992f4c..501f1d4f 100644 --- a/Documentation.md +++ b/Documentation.md @@ -7,7 +7,7 @@ Eiffel Web Framework, is mainly a collection of Eiffel libraries designed to be integrated with each other. One benefit is that it supports all core HTTP features, so enable you embrace HTTP as an application protocol to develop web applications. So you do not need to adapt your applications to the web, instead you use the web power. It means you can build different kind of web applications, from Web APIs following the Hypermedia API style (REST style), CRUD web services or just conventional web applications building a session on top of an stateless protocol. # EWF core/kernel -_ The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_). _ +_The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_)._ To build a web [service](#service), the framework provides a set of core components to launch the service, for each [request](#request-and-response), access the data, and send the [response](#request-and-response). The framework also provides a router component to help dispatching the incoming request. From 8696681710c7c5c6568b6b904cfb97aa3bbf5681 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:28:25 -0800 Subject: [PATCH 06/21] Updated Documentation (markdown) --- Documentation.md | 156 ++++++++++++++++++++++++----------------------- 1 file changed, 81 insertions(+), 75 deletions(-) diff --git a/Documentation.md b/Documentation.md index 501f1d4f..992e83dc 100644 --- a/Documentation.md +++ b/Documentation.md @@ -7,7 +7,7 @@ Eiffel Web Framework, is mainly a collection of Eiffel libraries designed to be integrated with each other. One benefit is that it supports all core HTTP features, so enable you embrace HTTP as an application protocol to develop web applications. So you do not need to adapt your applications to the web, instead you use the web power. It means you can build different kind of web applications, from Web APIs following the Hypermedia API style (REST style), CRUD web services or just conventional web applications building a session on top of an stateless protocol. # EWF core/kernel -_The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_)._ +> The Web Server Foundation (WSF\_) is the core of the framework. It is compliant with the EWSGI interface (WGI\_). To build a web [service](#service), the framework provides a set of core components to launch the service, for each [request](#request-and-response), access the data, and send the [response](#request-and-response). The framework also provides a router component to help dispatching the incoming request. @@ -16,7 +16,7 @@ A service can be a web api, a web interface, … what ever run on top of HTTP. # Service -_ see interface: **WSF_SERVICE** _ +> see interface: **WSF_SERVICE** Each incoming http request is processed by the following routine. @@ -28,20 +28,20 @@ For convenience, the framework provides richer service interface that handles th # Request and Response -_ see interface: **WSF_REQUEST** and **WSF_RESPONSE** _ +> see interface: **WSF_REQUEST** and **WSF_RESPONSE** Any incoming http request is represented by an new object of type **WSF_REQUEST**. **WSF_REQUEST** provides access to -* meta variables: CGI variables (coming from the request http header) -* query parameters: from the uri ex: ?q=abc&type=pdf -* input data: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. -* form parameters: standard parameters from the request input data. +* __meta variables__: CGI variables (coming from the request http header) +* __query parameters__: from the uri ex: ?q=abc&type=pdf +* __input data__: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. +* __form parameters__: standard parameters from the request input data. *typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` *(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) -* uploaded files: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. -* cookies variable: cookies extracted from the http header. +* __uploaded files__: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. +* __cookies variable__: cookies extracted from the http header. * path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) -* execution variables: used by the application to keep value associated with the request. +* __execution variables__: used by the application to keep value associated with the request. The **WSF_RESPONSE** represents the communication toward the client, a service need to provide correct headers, and content. For instance the `Content-Type`, and `Content-Length`. It also allows to send data with chunked encoding. @@ -49,137 +49,143 @@ The **WSF_RESPONSE** represents the communication toward the client, a service n # Connectors: -_see **WGI_CONNECTOR**_ +> see **WGI_CONNECTOR** + Using EWF, your service is built on top of underlying httpd solution/connectors. -Currently 3 main connectors are availables: -CGI: following the CGI interface, this is an easy solution to run the service on any platform. -libFCGI: based on the libfcgi solution, this can be used with apache, IIS, nginx, … -nino: a standalone server: Eiffel Web Nino allow you to embed a web server anywhere, on any platform without any dependencies on other httpd server. +Currently 3 main connectors are available: +* __CGI__: following the CGI interface, this is an easy solution to run the service on any platform. +* __libFCGI__: based on the libfcgi solution, this can be used with Apache, IIS, nginx, … +* __nino__: a standalone server: Eiffel Web Nino allow you to embed a web server anywhere, on any platform without any dependencies on other httpd server. + At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. It is fairly easy to add new connector, it just has to follow the EWSGI interface -Router or Request Dispatcher: -Routes HTTP requests to the proper execution code + + +# Router or Request Dispatcher: +> Routes HTTP requests to the proper execution code + A web application needs to have a clean and elegant URL scheme, and EWF provides a router component to design URLs. The association between a URL pattern and the code handling the URL request is called a Router mapping in EWF. EWF provides 3 main kinds of mappings -URI: any URL with path being the specified uri. -example: “/users/” redirects any “/users/” and “/users/?query=...” -URI-template: any URL matching the specified URI-template -example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” -Starts-with: any URL starting with the specified path +* __URI__: any URL with path being the specified uri. + * example: “/users/” redirects any “/users/” and “/users/?query=...” +* __URI-template__: any URL matching the specified URI-template + * example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” +* __Starts-with__: any URL starting with the specified path + Note: in the future, a Regular-Expression based kind will be added in the future, and it is possible to use custom mapping on top of EWF. Code: +` router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( “/project/{name}”, project_handler) ) -- And precising the request methods router.map_with_request_methods ( … , router.methods_GET_POST) +` - -In the previous code, the `project_handler’ is an object conforming to WSF_HANDLER, that will process the incoming requests matching URI-template “/project/{name}”. +In the previous code, the `project_handler` is an object conforming to **WSF_HANDLER**, that will process the incoming requests matching URI-template “/project/{name}”. Usually, the service will inherit from WSF_ROUTED_SERVICE, which has a `router’ attribute. Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_router’. To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map’ URI template with agent, and so on. See -map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) -map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]]) -and same with request methodes … +* map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) +* map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]]) +* and same with request methods … … Check WSF_*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. - - - How we do that in EWF? : Router with (or without context). Related code: wsf_router, wsf_router_context Examples -EWF components -URI Handler: - Parses the details of the URI (scheme, path, query info, etc.) and exposes them for use. +# EWF components +## URI Handler: +> Parses the details of the URI (scheme, path, query info, etc.) and exposes them for use. How we do that in EWF?: URI Templates, but we could also use regex. Related code: uri_template Examples: -Mime Parser/ Content Negotiation: -Handles the details of determining the media type, language, encoding, compression (conneg). +## Mime Parser/ Content Negotiation: +> Handles the details of determining the media type, language, encoding, compression (conneg). How do we do that in EWF? Content_Negotiation library. Example -Request Handler -target of request dispatcher + uri handler. +## Request Handler +> target of request dispatcher + uri handler. Here is where we handle GET, POST PUT, etc. -Representation Mapping -Converts stored data into the proper representation for responses and handles incoming representations from requests. +## Representation Mapping +> Converts stored data into the proper representation for responses and handles incoming representations from requests. We don’t have a representation library, the developer need to do that. If we want to provide different kind of representations: JSON, XML, HTML, the responsibility is let to the developer to map their domain to the target representation. -Http Client: - A simple library to make requests and handle responses from other http servers. +## Http Client: +> A simple library to make requests and handle responses from other http servers. How we do that in EWF? http client library examples: -Authentication/Security: - Handle differents auth models. (Basic, Digest?, OAuth, OpenId) +## Authentication/Security: +> Handle different auth models. (Basic, Digest?, OAuth, OpenId) How we do that in EWF? http_authorization, OpenId, and Cypress examples. -Caching: - Support for Caching and conditional request +## Caching: +> Support for Caching and conditional request How we do that in Eiffel? Policy framework on top of EWF. {{{need_review}}} examples -EWF HTML5 Widgets +## EWF HTML5 Widgets -EWF policy Framework +## EWF policy Framework -EWF application generators +## EWF application generators + +# EWSGI Specification -Specification -EWSGI + +# Libraries +External libraries are included, such as Cypress OAuth (Security), HTML parsing library, Template Engine Smarty. +## server +* __ewsgi__: Eiffel Web Server Gateway Interface read more + * connectors: various web server connectors for EWSGI +* __libfcgi__: Wrapper for libfcgi SDK +* __wsf__: Web Server Framework [read more] + * __router__: URL dispatching/routing based on uri, uri_template, or custom read more + * __wsf_html__: (html and css) Content generator from the server side. + * CMS example: -Libraries +## protocol +* __http__: HTTP related classes, constants for status code, content types, ... read more +* __uri_template__: URI Template library (parsing and expander) read more +* __content_negotiation__: CONNEG library (Content-type Negociation) read more -I’m including external libraries, like Cypress OAuth (Security), HTML parsing library, Template Engine Smarty. +## Client +* __http_client__: simple HTTP client based on cURL readmore +* __Firebase API__: +## Text +* __encoder__: Various simple encoders: base64, url-encoder, xml entities, html entities read more -server -ewsgi: Eiffel Web Server Gateway Interface read more -connectors: various web server connectors for EWSGI -libfcgi: Wrapper for libfcgi SDK -wsf: Web Server Framework read more -router: URL dispatching/routing based on uri, uri_template, or custom read more -wsf_html: (html and css) Content generator from the server side. -CMS example: https://github.com/EiffelWebFramework/cms/tree/master/example -protocol -http: HTTP related classes, constants for status code, content types, ... read more -uri_template: URI Template library (parsing and expander) read more -content_negotiation: CONNEG library (Content-type Negociation) read more -Client -http_client: simple HTTP client based on cURL readmore -Firebase API: https://github.com/EiffelWebFramework/Redwood -Text -encoder: Various simpler encoders: base64, url-encoder, xml entities, html entities read more -Utils -error: very simple/basic library to handle error -Security -http_authentication (under EWF/library/server/authentication) -open_id (under EWF/library/security) -OAuth (https://github.com/EiffelWebFramework/cypress) +## Utils +* __error__: very simple/basic library to handle error + +## Security +* __http_authentication__ (under EWF/library/server/authentication) +* __open_id__ (under EWF/library/security) +* __OAuth__ see From 992504a49fc35a648172e248b41d3106624904a3 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:33:37 -0800 Subject: [PATCH 07/21] Updated Documentation (markdown) --- Documentation.md | 60 +++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/Documentation.md b/Documentation.md index 992e83dc..97059757 100644 --- a/Documentation.md +++ b/Documentation.md @@ -22,9 +22,9 @@ Each incoming http request is processed by the following routine. > `{WSF_SERVICE}.execute (req: WSF_REQUEST; res: WSF_RESPONSE)` -This is the low level of the framework, at this point, `req’ provides access to the query and form parameters, input data, headers, … as specified by the Common Gateway Interface (CGI). -The response `res’ is the interface to send data back to the client. -For convenience, the framework provides richer service interface that handles the most common needs (filter, router, …). +This is the low level of the framework, at this point, `req` provides access to the query and form parameters, input data, headers, ... as specified by the Common Gateway Interface (CGI). +The response `res` is the interface to send data back to the client. +For convenience, the framework provides richer service interface that handles the most common needs (filter, router, ...). # Request and Response @@ -32,16 +32,16 @@ For convenience, the framework provides richer service interface that handles th Any incoming http request is represented by an new object of type **WSF_REQUEST**. **WSF_REQUEST** provides access to -* __meta variables__: CGI variables (coming from the request http header) -* __query parameters__: from the uri ex: ?q=abc&type=pdf -* __input data__: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. -* __form parameters__: standard parameters from the request input data. - *typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` - *(advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) -* __uploaded files__: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. -* __cookies variable__: cookies extracted from the http header. -* path parameters: note this is related to the router and carry the semantic of the mapping (see the section on router ) -* __execution variables__: used by the application to keep value associated with the request. ++ __meta variables__: CGI variables (coming from the request http header) ++ __query parameters__: from the uri ex: `?q=abc&type=pdf` ++ __input data__: the message of the request, if this is a web form, this is parsed to build the form parameters. It can be retrieved once. ++ __form parameters__: standard parameters from the request input data. + - typically available when a web form is sent using POST as content of type `multipart/form-data` or `application/x-www-form-urlencoded` + - (advanced usage: it is possible to write mime handler that can processed other type of content, even custom format.) ++ __uploaded files__: if files are uploaded, their value will be available from the form parameters, and from the uploaded files as well. ++ __cookies variable__: cookies extracted from the http header. ++ __path parameters__: note this is related to the router and carry the semantic of the mapping (see the section on router ) ++ __execution variables__: used by the application to keep value associated with the request. The **WSF_RESPONSE** represents the communication toward the client, a service need to provide correct headers, and content. For instance the `Content-Type`, and `Content-Length`. It also allows to send data with chunked encoding. @@ -54,7 +54,7 @@ The **WSF_RESPONSE** represents the communication toward the client, a service n Using EWF, your service is built on top of underlying httpd solution/connectors. Currently 3 main connectors are available: * __CGI__: following the CGI interface, this is an easy solution to run the service on any platform. -* __libFCGI__: based on the libfcgi solution, this can be used with Apache, IIS, nginx, … +* __libFCGI__: based on the libfcgi solution, this can be used with Apache, IIS, nginx, ... * __nino__: a standalone server: Eiffel Web Nino allow you to embed a web server anywhere, on any platform without any dependencies on other httpd server. At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. @@ -69,22 +69,20 @@ A web application needs to have a clean and elegant URL scheme, and EWF provides The association between a URL pattern and the code handling the URL request is called a Router mapping in EWF. EWF provides 3 main kinds of mappings -* __URI__: any URL with path being the specified uri. - * example: “/users/” redirects any “/users/” and “/users/?query=...” -* __URI-template__: any URL matching the specified URI-template - * example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” -* __Starts-with__: any URL starting with the specified path ++ __URI__: any URL with path being the specified uri. + - example: “/users/” redirects any “/users/” and “/users/?query=...” ++ __URI-template__: any URL matching the specified URI-template + - example: “/project/{name}/” redirects any “/project/foo” or “/project/bar” ++ __Starts-with__: any URL starting with the specified path Note: in the future, a Regular-Expression based kind will be added in the future, and it is possible to use custom mapping on top of EWF. Code: -` -router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( -“/project/{name}”, project_handler) -) - -- And precising the request methods -router.map_with_request_methods ( … , router.methods_GET_POST) -` +> router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( +> “/project/{name}”, project_handler) +> ) +> -- And precising the request methods +> router.map_with_request_methods ( … , router.methods_GET_POST) In the previous code, the `project_handler` is an object conforming to **WSF_HANDLER**, that will process the incoming requests matching URI-template “/project/{name}”. @@ -93,11 +91,11 @@ Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_ To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map’ URI template with agent, and so on. See -* map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER) -* map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]]) -* and same with request methods … -… -Check WSF_*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. ++ `map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER)` ++ `map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]])` ++ and same with request methods ... +... +Check WSF_\*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. How we do that in EWF? : Router with (or without context). Related code: wsf_router, wsf_router_context From 2fb521aa42fa2d511a3991745f222f9243781dfe Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 03:37:03 -0800 Subject: [PATCH 08/21] Updated Documentation (markdown) --- Documentation.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/Documentation.md b/Documentation.md index 97059757..f77fced5 100644 --- a/Documentation.md +++ b/Documentation.md @@ -78,23 +78,26 @@ EWF provides 3 main kinds of mappings Note: in the future, a Regular-Expression based kind will be added in the future, and it is possible to use custom mapping on top of EWF. Code: -> router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( -> “/project/{name}”, project_handler) -> ) -> -- And precising the request methods -> router.map_with_request_methods ( … , router.methods_GET_POST) + + router.map ( create {WSF_URI_TEMPLATE_MAPPING}.make ( + “/project/{name}”, project_handler) + ) + -- And precising the request methods + router.map_with_request_methods ( ... , router.methods_GET_POST) In the previous code, the `project_handler` is an object conforming to **WSF_HANDLER**, that will process the incoming requests matching URI-template “/project/{name}”. -Usually, the service will inherit from WSF_ROUTED_SERVICE, which has a `router’ attribute. -Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_router’. +Usually, the service will inherit from WSF_ROUTED_SERVICE, which has a `router` attribute. +Configuring the URL scheme is done by implementing `{WSF_ROUTED_SERVICE}.setup_router`. -To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map’ URI template with agent, and so on. +To make life easier, by inheriting from WSF_URI_TEMPLATE_HELPER_FOR_ROUTED_SERVICE, a few help methods are available to `map` URI template with agent, and so on. See + `map_uri_template (a_tpl: STRING; h: WSF_URI_TEMPLATE_HANDLER)` + `map_uri_template_agent (a_tpl: READABLE_STRING_8; proc: PROCEDURE [ANY, TUPLE [req: WSF_REQUEST; res: WSF_RESPONSE]])` + and same with request methods ... + ... + Check WSF_\*_HELPER_FOR_ROUTED_SERVICE for other available helper classes. How we do that in EWF? : Router with (or without context). From 093dec180880e5a5cd8a1f9a3e083401b800b897 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 04:22:11 -0800 Subject: [PATCH 09/21] Updated Documentation (markdown) --- Documentation.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation.md b/Documentation.md index f77fced5..de3dad1c 100644 --- a/Documentation.md +++ b/Documentation.md @@ -29,6 +29,7 @@ For convenience, the framework provides richer service interface that handles th # Request and Response > see interface: **WSF_REQUEST** and **WSF_RESPONSE** + Any incoming http request is represented by an new object of type **WSF_REQUEST**. **WSF_REQUEST** provides access to @@ -107,6 +108,7 @@ Examples # EWF components ## URI Handler: > Parses the details of the URI (scheme, path, query info, etc.) and exposes them for use. + How we do that in EWF?: URI Templates, but we could also use regex. Related code: uri_template Examples: @@ -114,12 +116,14 @@ Examples: ## Mime Parser/ Content Negotiation: > Handles the details of determining the media type, language, encoding, compression (conneg). + How do we do that in EWF? Content_Negotiation library. Example ## Request Handler -> target of request dispatcher + uri handler. +> target of request dispatcher + uri handler. + Here is where we handle GET, POST PUT, etc. ## Representation Mapping @@ -131,22 +135,23 @@ to the developer to map their domain to the target representation. ## Http Client: > A simple library to make requests and handle responses from other http servers. + How we do that in EWF? http client library examples: ## Authentication/Security: > Handle different auth models. (Basic, Digest?, OAuth, OpenId) + How we do that in EWF? http_authorization, OpenId, and Cypress examples. ## Caching: > Support for Caching and conditional request + How we do that in Eiffel? Policy framework on top of EWF. {{{need_review}}} examples - - ## EWF HTML5 Widgets ## EWF policy Framework From 580739d0b42e06b2b6306c6f26cbe23ad43a8683 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 04:52:59 -0800 Subject: [PATCH 10/21] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index fdb4420a..1b07b8ae 100644 --- a/Home.md +++ b/Home.md @@ -9,7 +9,7 @@ The official documentation/wiki is located at [https://github.com/EiffelWebFrame - For time to time we have [web meetings](./wiki/Meetings), and less frequently [physical meetings](./wiki/Meetings) that occurs usually during other Eiffel related events. ## Documentation ## -- to redo +- [Documentation](./wiki/Documentation) ## Contributions ## - You want to contribute or follow the progress/discussion, see the [collaboration page](./wiki/Community-collaboration) From d1238a441d5b21171bbb73cd7eb06f785e84c81d Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:06:13 -0800 Subject: [PATCH 11/21] Created Documentation__Service (markdown) --- Documentation__Service.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Documentation__Service.md diff --git a/Documentation__Service.md b/Documentation__Service.md new file mode 100644 index 00000000..ea6d16b5 --- /dev/null +++ b/Documentation__Service.md @@ -0,0 +1,2 @@ +EWF Services +> See WSF\_SERVICE \ No newline at end of file From b312d69afa8619c6a35ee44e0da036fb7a32d28b Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:08:47 -0800 Subject: [PATCH 12/21] Updated Documentation (markdown) --- Documentation.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Documentation.md b/Documentation.md index de3dad1c..b50d51b7 100644 --- a/Documentation.md +++ b/Documentation.md @@ -26,6 +26,8 @@ This is the low level of the framework, at this point, `req` provides access to The response `res` is the interface to send data back to the client. For convenience, the framework provides richer service interface that handles the most common needs (filter, router, ...). +[Learn more about service](Documentation__Service) + # Request and Response > see interface: **WSF_REQUEST** and **WSF_RESPONSE** @@ -46,7 +48,7 @@ Any incoming http request is represented by an new object of type **WSF_REQUEST* The **WSF_RESPONSE** represents the communication toward the client, a service need to provide correct headers, and content. For instance the `Content-Type`, and `Content-Length`. It also allows to send data with chunked encoding. -{{Learn more}} +> [Learn more about request](Documentation__Request) and [about response](Documentation__Response) # Connectors: @@ -61,6 +63,8 @@ Currently 3 main connectors are available: At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. It is fairly easy to add new connector, it just has to follow the EWSGI interface +[Learn more about connector](Documentation__Connector) + # Router or Request Dispatcher: > Routes HTTP requests to the proper execution code @@ -105,6 +109,8 @@ How we do that in EWF? : Router with (or without context). Related code: wsf_router, wsf_router_context Examples +[Learn more about router](Documentation__Router) + # EWF components ## URI Handler: > Parses the details of the URI (scheme, path, query info, etc.) and exposes them for use. From b81207e42e754f78512188ea189491197f2af2cd Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:09:21 -0800 Subject: [PATCH 13/21] Created Documentation _Router (markdown) --- Documentation-_Router.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation-_Router.md diff --git a/Documentation-_Router.md b/Documentation-_Router.md new file mode 100644 index 00000000..3207e4a6 --- /dev/null +++ b/Documentation-_Router.md @@ -0,0 +1 @@ +See WSF_ROUTER \ No newline at end of file From 06c5f068db91044176bd46a882696d4103af7d16 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:10:04 -0800 Subject: [PATCH 14/21] Created Documentation__Request (markdown) --- Documentation__Request.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation__Request.md diff --git a/Documentation__Request.md b/Documentation__Request.md new file mode 100644 index 00000000..09b73ab0 --- /dev/null +++ b/Documentation__Request.md @@ -0,0 +1 @@ +See WSF_REQUEST \ No newline at end of file From c8e9a835f5c9e43a0c2ed079f50d0db668f54b68 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:10:14 -0800 Subject: [PATCH 15/21] Created Documentation__Response (markdown) --- Documentation__Response.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation__Response.md diff --git a/Documentation__Response.md b/Documentation__Response.md new file mode 100644 index 00000000..400c54e3 --- /dev/null +++ b/Documentation__Response.md @@ -0,0 +1 @@ +See WSF_RESPONSE \ No newline at end of file From e832478b76245eb91f8c930a7f73ae34d31d1da3 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:10:23 -0800 Subject: [PATCH 16/21] Updated Documentation _Router (markdown) From 6acdcb4e6dfb31fdbc30acab529b8346074301c9 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:10:44 -0800 Subject: [PATCH 17/21] Created Documentation__Router (markdown) --- Documentation__Router.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation__Router.md diff --git a/Documentation__Router.md b/Documentation__Router.md new file mode 100644 index 00000000..3207e4a6 --- /dev/null +++ b/Documentation__Router.md @@ -0,0 +1 @@ +See WSF_ROUTER \ No newline at end of file From 69b67b3b4b9c4be435125e1a526e938ef5a25109 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:11:40 -0800 Subject: [PATCH 18/21] Updated Documentation (markdown) --- Documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation.md b/Documentation.md index b50d51b7..ad1d2494 100644 --- a/Documentation.md +++ b/Documentation.md @@ -26,7 +26,7 @@ This is the low level of the framework, at this point, `req` provides access to The response `res` is the interface to send data back to the client. For convenience, the framework provides richer service interface that handles the most common needs (filter, router, ...). -[Learn more about service](Documentation__Service) +> [Learn more about service](Documentation__Service) # Request and Response @@ -63,7 +63,7 @@ Currently 3 main connectors are available: At compilation time, you can use a default connector (by using the associated default lib), but you can also use a mixed of them and choose which one to execute at runtime. It is fairly easy to add new connector, it just has to follow the EWSGI interface -[Learn more about connector](Documentation__Connector) +> [Learn more about connector](Documentation__Connector) # Router or Request Dispatcher: @@ -109,7 +109,7 @@ How we do that in EWF? : Router with (or without context). Related code: wsf_router, wsf_router_context Examples -[Learn more about router](Documentation__Router) +> [Learn more about router](Documentation__Router) # EWF components ## URI Handler: From 48deb869de82bd61370489099a35d22865b06e76 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Tue, 7 Jan 2014 05:12:09 -0800 Subject: [PATCH 19/21] Created Documentation__Connector (markdown) --- Documentation__Connector.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation__Connector.md diff --git a/Documentation__Connector.md b/Documentation__Connector.md new file mode 100644 index 00000000..b76dce29 --- /dev/null +++ b/Documentation__Connector.md @@ -0,0 +1 @@ +See WSF_CONNECTOR \ No newline at end of file From e9b4a8abd50fd2a5ad1198c9b2796eab28e7ce70 Mon Sep 17 00:00:00 2001 From: Jocelyn Fiat Date: Mon, 3 Feb 2014 09:38:20 -0800 Subject: [PATCH 20/21] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 1b07b8ae..16806d74 100644 --- a/Home.md +++ b/Home.md @@ -9,7 +9,7 @@ The official documentation/wiki is located at [https://github.com/EiffelWebFrame - For time to time we have [web meetings](./wiki/Meetings), and less frequently [physical meetings](./wiki/Meetings) that occurs usually during other Eiffel related events. ## Documentation ## -- [Documentation](./wiki/Documentation) +- [Documentation](./Documentation) ## Contributions ## - You want to contribute or follow the progress/discussion, see the [collaboration page](./wiki/Community-collaboration) From 7abbc963475369cf32ef5b479035fceb53f6b675 Mon Sep 17 00:00:00 2001 From: colin-adams Date: Tue, 11 Feb 2014 00:39:03 -0800 Subject: [PATCH 21/21] Removed warning about not being part of release. --- Using-the-policy-driven-framework.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/Using-the-policy-driven-framework.md b/Using-the-policy-driven-framework.md index bf85c9ef..12d085e4 100644 --- a/Using-the-policy-driven-framework.md +++ b/Using-the-policy-driven-framework.md @@ -1,7 +1,5 @@ # Using the policy driven framework -**This describes a new facility that is not yet in the EWF release** - ## Introduction The aim of the policy-driven framework is to allow authors of web-servers to concentrate on the business logic (e.g., in the case of a GET request, generating the content), without having to worry about the details of the HTTP protocol (such as headers and response codes). However, there are so many possibilities in the HTTP protocol, that it is impossible to correctly guess what to do in all cases. Therefore the author has to supply policy decisions to the framework, in areas such as caching decisions. These are implemented as a set of deferred classes for which the author needs to provide effective implementations.