Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 139 lines (97 sloc) 7.679 kb
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
1 <h1>Simple Bridge</h1>
2
d15bd36d » rustyio
2009-09-27 Update README.
3 Simple Bridge takes the pain out of coding to multiple Erlang web servers by creating a standardized interface. It is used by the soon to be released new version of <a href="http://nitrogenproject.com">The Nitrogen Web Framework</a>.
4
5 In a sense, it is similar to <a href="http://github.com/skarab/ewgi">EWGI</a>, except SimpleBridge has some key improvements/differences:
6
7 * <b>Smaller code base</b> SimpleBridge is 870 lines, compared to 1,974 lines for EWGI. This is because SimpleBridge uses the underlying HTTP server's built in parsing functions as much as possible.
8 * <b>Easily extended</b> - Takes about 150 lines to add support for a new HTTP server, vs. ~350 for EWGI.
9 * <b>MultiPart File Uploads</b> - SimpleBridge has better support for HTTP POSTS, including support for multipart file uploads, with size limits and handle-able errors.
10 * <b>Static File Support</b> - Support for sending a static file to the browser, using the underlying HTTP server's own methods.
11 * <b>Cookies Support</b> - SimpleBridge provides interface functions for getting and setting cookies.
12 * <b>No Middleware Components</b> - One disadvantage, SimpleBridge does not explicitly support EWGI's concept of "middleware components". (Though you could probably fake it, haven't tried.)
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
13
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
14 Simple Bridge is split into two parts:
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
15
d15bd36d » rustyio
2009-09-27 Update README.
16 * A *Request Bridge* is a parameterized module that allows you to see information about the incoming request.
17 * A *Response Bridge* is a parameterized module that allows you to construct a response.
18
aa81244c » rustyio
2009-09-27 Formatting.
19 </h2>Hello World Example</h2>
d15bd36d » rustyio
2009-09-27 Update README.
20
57bab9e6 » rustyio
2009-09-27 Fix formatting.
21 % SimpleBridge Hello World Example in Mochiweb
22
23 start(_, _) ->
24 Options = [{ip, "127.0.0.1"}, {port, 8000}],
25 Loop = fun loop/1,
26 mochiweb_http:start([{name, mochiweb_example_app}, {loop, Loop} | Options]).
27
28 loop(Req) ->
29 Request = simple_bridge:make_request(mochiweb_request_bridge, {Req, "./wwwroot"}),
30 HTML = [
31 "&lt;h1&gt;Hello, World!&lt;/h1&gt;",
32 io_lib:format("METHOD: ~p~n&lt;br&gt;&lt;br&gt;", [Request:request_method()]),
33 io_lib:format("COOKIES: ~p~n&lt;br&gt;&lt;br&gt;", [Request:cookies()]),
34 io_lib:format("HEADERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:headers()]),
35 io_lib:format("QUERY PARAMETERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:query_params()])
36 ],
37
38 Response = simple_bridge:make_response(mochiweb_response_bridge, {Req, "./wwwroot"}),
39 Response1 = Response:status_code(200),
40 Response2 = Response1:header("Content-Type", "text/html"),
41 Response3 = Response2:data(HTML),
42 Response3:build_response().
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
43
44
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
45 <h2>Request Bridges</h2>
46 <h4>How do I make a request bridge?</h4>
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
47
c639d635 » rustyio
2009-09-04 Change interfaces.
48 To make a request bridge for an incoming request, call the simple_bridge:make_request/2 function,
d15bd36d » rustyio
2009-09-27 Update README.
49 specifying the appropriate bridge module for your HTTP server, and the arguments that it needs. This code would sit in the loop/1 function of a Mochiweb server, or the do/1 function of an Inets server.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
50
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
51 Inets example:
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
52
d15bd36d » rustyio
2009-09-27 Update README.
53 RequestBridge = simple_bridge:make_request(inets_response_bridge, Info)
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
54
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
55 Mochiweb example:
56
d15bd36d » rustyio
2009-09-27 Update README.
57 RequestBridge = simple_bridge:make_request(mochiweb_response_bridge, [{Req, Docroot}]).
58
59
60 <h4>What can I do with the request bridge object?</h4>
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
61
d15bd36d » rustyio
2009-09-27 Update README.
62 Once you have created the request bridge object (a parameterized module), it provides you with a standard interface for accessing the request method, path, query parameters, post parameters, headers, and cookies of the request:
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
63
d15bd36d » rustyio
2009-09-27 Update README.
64 Request Bridge Interface:
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
65
66 * *Bridge:request_method()* - returns 'GET', 'POST', 'HEAD', etc.
67 * *Bridge:path()* - returns the requested path and file.
68 * *Bridge:peer_ip()* - returns the client's IP address in tuple format (74.125.67.100 = {74, 125, 67, 100})
69 * *Bridge:peer_port()* - returns the client's port.
d15bd36d » rustyio
2009-09-27 Update README.
70 * *Bridge:headers()* - returns a proplist of headers, [{header1, "Value1"}, {header2, "Value2"}, ...]
71 * *Bridge:header(Header)* - returns the value of a header.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
72 * *Bridge:cookies()* - returns a proplist of cookies, [{"Cookie1", "Value1"}, {"Cookie2", "Value2"}, ...]
73 * *Bridge:query_params()* - returns a proplist of query params, [{"Query1", "Value1"}, {"Query2", "Value2"}, ...]
d15bd36d » rustyio
2009-09-27 Update README.
74 * *Bridge:post_params()* - returns a proplist of post params, [{"Post1", "Value1"}, {"Post2", "Value2"}, ...]
75 * *Bridge:post_files()* - returns a list of upload_file records, describing the files uploaded in a multipart post.
76 * *Bridge:request_body()* - returns the request body that has been read so far, as a list.
77 * *Bridge:error()* - returns an Erlang term describing any errors that happened while parsing a multipart post.
57bab9e6 » rustyio
2009-09-27 Fix formatting.
78
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
79 <h4>What modules are involved in a request bridge?</h4>
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
80
81 * *request_bridge.erl* - The behaviour interface that request bridge modules must implement.
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
82 * *request_bridge_wrapper.erl* - A parameterized module that wraps a request.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
83 * *inets_request_bridge.erl* - The request bridge module for Inets.
84 * *mochiweb_request_bridge.erl* - The request bridge module for Mochiweb.
d15bd36d » rustyio
2009-09-27 Update README.
85 * *???_request_bridge.erl* - Support for more servers on the way.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
86
d15bd36d » rustyio
2009-09-27 Update README.
87 To extend the Simple Bridge to work with other HTTP servers (or other versions of Inets, Mochiweb, or Yaws), copy and modify inets_request_bridge.erl or mochiweb_request_bridge.erl.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
88
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
89 <h2>Response Bridges</h2>
90 <h4>How do I make a response bridge?</h4>
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
91
d15bd36d » rustyio
2009-09-27 Update README.
92 To make a request bridge for an incoming request, call the simple_bridge:make_response/2 function,
93 specifying the appropriate bridge module for your HTTP server, and the arguments that it needs. This code would sit in the loop/1 function of a Mochiweb server, or the do/1 function of an Inets server.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
94
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
95 Inets example:
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
96
57bab9e6 » rustyio
2009-09-27 Fix formatting.
97 ResponseBridge = simple_bridge:make_response(inets_response_bridge, Info)
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
98
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
99 Mochiweb example:
100
57bab9e6 » rustyio
2009-09-27 Fix formatting.
101 ResponseBridge = simple_bridge:make_response(mochiweb_response_bridge, {Req, Docroot})
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
102
103 <h4>What can I do with the response bridge?</h4>
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
104
d15bd36d » rustyio
2009-09-27 Update README.
105 Once you have created the request bridge object (a parameterized module), it provides you with a standard interface for combining headers, cookies, and a response body into a response appropriate for your http server.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
106
107 Each function below returns a new bridge object, so your will need to
108 chain together requests like this:
109
d15bd36d » rustyio
2009-09-27 Update README.
110 Bridge = simple_bridge:make_response(inets_response_bridge, Info),
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
111 Bridge1 = Bridge:status_code(200),
112 Bridge2 = Bridge1:header("Header1", "Value1"),
d15bd36d » rustyio
2009-09-27 Update README.
113 Bridge3 = Bridge2:data(HTML),
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
114 etc.
d15bd36d » rustyio
2009-09-27 Update README.
115
116 Response Bridge Interface:
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
117
118 * *Bridge:status_code(Code)* - set the HTTP status code. (200, 404, etc.)
119 * *Bridge:header(Name, Value)* - set an HTTP header.
120 * *Bridge:clear_headers()* - clear all previously set headers.
121 * *Bridge:cookie(Name, Value)* - set a cookie for path "/" with expiration in 20 minutes.
122 * *Bridge:cookie(Name, Value, Path, Exp)* - Set a cookie. Exp is an integer in minutes.
123 * *Bridge:clear_cookies()* - clear all previously set cookies.
124 * *Bridge:data(Data)* - set the data to return in the response. Usually HTML goes here.
d15bd36d » rustyio
2009-09-27 Update README.
125 * *Bridge:file(File)* - Send a static file to the browser.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
126
127 Finally, you build the response to send to your HTTP server with the build_response/0 function.
128
129 * *Bridge:build_response()* - Create a response tuple that you can hand off to your HTTP server.
130
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
131 <h4>What modules are involved in a response bridge?</h4>
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
132
133 * *response_bridge.erl* - The behaviour interface that response bridge modules must implement.
d198fc3a » rustyio
2009-05-16 Clean up README syntax.
134 * *response_bridge_wrapper.erl* - A parameterized module that wraps a response.
951cc9d0 » rustyio
2009-05-16 Finish unit tests for Inets Request. Implement Inets Response. Add un…
135 * *inets_response_bridge.erl* - The response bridge module for Inets.
136 * *mochiweb_response_bridge.erl* - The response bridge module for Mochiweb.
137
138 To extend the Simple Bridge to other HTTP servers (or other versions of Inets, Mochiweb, or Yaws),
d15bd36d » rustyio
2009-09-27 Update README.
139 copy and modify inets_response_bridge.erl or mochiweb_response_bridge.erl.
Something went wrong with that request. Please try again.