Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 148 lines (98 sloc) 7.754 kb
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
1 <h1>Simple Bridge</h1>
2
d15bd36 @rustyio Update README.
rustyio authored
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
e2beb14 @rustyio Formatting.
rustyio authored
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.
d15bd36 @rustyio Update README.
rustyio authored
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.
e2beb14 @rustyio Formatting.
rustyio authored
12 * <b>No Middleware Components</b> - SimpleBridge does not explicitly support EWGI's concept of "middleware components". (Though you could probably fake it, haven't tried.)
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
13
d198fc3 @rustyio Clean up README syntax.
rustyio authored
14 Simple Bridge is split into two parts:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
15
d15bd36 @rustyio Update README.
rustyio authored
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
9c39705 @rustyio Formatting.
rustyio authored
19
aa81244 @rustyio Formatting.
rustyio authored
20 </h2>Hello World Example</h2>
d15bd36 @rustyio Update README.
rustyio authored
21
57bab9e @rustyio Fix formatting.
rustyio authored
22 % SimpleBridge Hello World Example in Mochiweb
23
24 start(_, _) ->
25 Options = [{ip, "127.0.0.1"}, {port, 8000}],
26 Loop = fun loop/1,
27 mochiweb_http:start([{name, mochiweb_example_app}, {loop, Loop} | Options]).
28
29 loop(Req) ->
30 Request = simple_bridge:make_request(mochiweb_request_bridge, {Req, "./wwwroot"}),
31 HTML = [
32 "&lt;h1&gt;Hello, World!&lt;/h1&gt;",
33 io_lib:format("METHOD: ~p~n&lt;br&gt;&lt;br&gt;", [Request:request_method()]),
34 io_lib:format("COOKIES: ~p~n&lt;br&gt;&lt;br&gt;", [Request:cookies()]),
35 io_lib:format("HEADERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:headers()]),
36 io_lib:format("QUERY PARAMETERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:query_params()])
37 ],
38
39 Response = simple_bridge:make_response(mochiweb_response_bridge, {Req, "./wwwroot"}),
40 Response1 = Response:status_code(200),
41 Response2 = Response1:header("Content-Type", "text/html"),
42 Response3 = Response2:data(HTML),
43 Response3:build_response().
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
44
45
d198fc3 @rustyio Clean up README syntax.
rustyio authored
46 <h2>Request Bridges</h2>
8566e10 @rustyio Formatting.
rustyio authored
47 <h3>How do I make a request bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
48
c639d63 @rustyio Change interfaces.
rustyio authored
49 To make a request bridge for an incoming request, call the simple_bridge:make_request/2 function,
d15bd36 @rustyio Update README.
rustyio authored
50 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.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
51
d198fc3 @rustyio Clean up README syntax.
rustyio authored
52 Inets example:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
53
d15bd36 @rustyio Update README.
rustyio authored
54 RequestBridge = simple_bridge:make_request(inets_response_bridge, Info)
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
55
d198fc3 @rustyio Clean up README syntax.
rustyio authored
56 Mochiweb example:
57
d15bd36 @rustyio Update README.
rustyio authored
58 RequestBridge = simple_bridge:make_request(mochiweb_response_bridge, [{Req, Docroot}]).
59
60
8566e10 @rustyio Formatting.
rustyio authored
61 <h3>What can I do with the request bridge object?</h3>
d198fc3 @rustyio Clean up README syntax.
rustyio authored
62
d15bd36 @rustyio Update README.
rustyio authored
63 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:
d198fc3 @rustyio Clean up README syntax.
rustyio authored
64
9c39705 @rustyio Formatting.
rustyio authored
65
8566e10 @rustyio Formatting.
rustyio authored
66 <h3>Request Bridge Interface</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
67
68 * *Bridge:request_method()* - returns 'GET', 'POST', 'HEAD', etc.
69 * *Bridge:path()* - returns the requested path and file.
70 * *Bridge:peer_ip()* - returns the client's IP address in tuple format (74.125.67.100 = {74, 125, 67, 100})
71 * *Bridge:peer_port()* - returns the client's port.
d15bd36 @rustyio Update README.
rustyio authored
72 * *Bridge:headers()* - returns a proplist of headers, [{header1, "Value1"}, {header2, "Value2"}, ...]
73 * *Bridge:header(Header)* - returns the value of a header.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
74 * *Bridge:cookies()* - returns a proplist of cookies, [{"Cookie1", "Value1"}, {"Cookie2", "Value2"}, ...]
75 * *Bridge:query_params()* - returns a proplist of query params, [{"Query1", "Value1"}, {"Query2", "Value2"}, ...]
d15bd36 @rustyio Update README.
rustyio authored
76 * *Bridge:post_params()* - returns a proplist of post params, [{"Post1", "Value1"}, {"Post2", "Value2"}, ...]
77 * *Bridge:post_files()* - returns a list of upload_file records, describing the files uploaded in a multipart post.
78 * *Bridge:request_body()* - returns the request body that has been read so far, as a list.
79 * *Bridge:error()* - returns an Erlang term describing any errors that happened while parsing a multipart post.
57bab9e @rustyio Fix formatting.
rustyio authored
80
9c39705 @rustyio Formatting.
rustyio authored
81
8566e10 @rustyio Formatting.
rustyio authored
82 <h3>What modules are involved in a request bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
83
84 * *request_bridge.erl* - The behaviour interface that request bridge modules must implement.
d198fc3 @rustyio Clean up README syntax.
rustyio authored
85 * *request_bridge_wrapper.erl* - A parameterized module that wraps a request.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
86 * *inets_request_bridge.erl* - The request bridge module for Inets.
87 * *mochiweb_request_bridge.erl* - The request bridge module for Mochiweb.
d15bd36 @rustyio Update README.
rustyio authored
88 * *???_request_bridge.erl* - Support for more servers on the way.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
89
d15bd36 @rustyio Update README.
rustyio authored
90 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.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
91
9c39705 @rustyio Formatting.
rustyio authored
92
d198fc3 @rustyio Clean up README syntax.
rustyio authored
93 <h2>Response Bridges</h2>
8566e10 @rustyio Formatting.
rustyio authored
94 <h3>How do I make a response bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
95
d15bd36 @rustyio Update README.
rustyio authored
96 To make a request bridge for an incoming request, call the simple_bridge:make_response/2 function,
97 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.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
98
d198fc3 @rustyio Clean up README syntax.
rustyio authored
99 Inets example:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
100
57bab9e @rustyio Fix formatting.
rustyio authored
101 ResponseBridge = simple_bridge:make_response(inets_response_bridge, Info)
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
102
d198fc3 @rustyio Clean up README syntax.
rustyio authored
103 Mochiweb example:
104
57bab9e @rustyio Fix formatting.
rustyio authored
105 ResponseBridge = simple_bridge:make_response(mochiweb_response_bridge, {Req, Docroot})
d198fc3 @rustyio Clean up README syntax.
rustyio authored
106
9c39705 @rustyio Formatting.
rustyio authored
107
8566e10 @rustyio Formatting.
rustyio authored
108 <h3>What can I do with the Response Bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
109
d15bd36 @rustyio Update README.
rustyio authored
110 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.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
111
112 Each function below returns a new bridge object, so your will need to
113 chain together requests like this:
114
d15bd36 @rustyio Update README.
rustyio authored
115 Bridge = simple_bridge:make_response(inets_response_bridge, Info),
d198fc3 @rustyio Clean up README syntax.
rustyio authored
116 Bridge1 = Bridge:status_code(200),
117 Bridge2 = Bridge1:header("Header1", "Value1"),
d15bd36 @rustyio Update README.
rustyio authored
118 Bridge3 = Bridge2:data(HTML),
d198fc3 @rustyio Clean up README syntax.
rustyio authored
119 etc.
d15bd36 @rustyio Update README.
rustyio authored
120
9c39705 @rustyio Formatting.
rustyio authored
121
8566e10 @rustyio Formatting.
rustyio authored
122 <h3>Response Bridge Interface</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
123
124 * *Bridge:status_code(Code)* - set the HTTP status code. (200, 404, etc.)
125 * *Bridge:header(Name, Value)* - set an HTTP header.
126 * *Bridge:clear_headers()* - clear all previously set headers.
127 * *Bridge:cookie(Name, Value)* - set a cookie for path "/" with expiration in 20 minutes.
128 * *Bridge:cookie(Name, Value, Path, Exp)* - Set a cookie. Exp is an integer in minutes.
129 * *Bridge:clear_cookies()* - clear all previously set cookies.
130 * *Bridge:data(Data)* - set the data to return in the response. Usually HTML goes here.
d15bd36 @rustyio Update README.
rustyio authored
131 * *Bridge:file(File)* - Send a static file to the browser.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
132
133 Finally, you build the response to send to your HTTP server with the build_response/0 function.
134
135 * *Bridge:build_response()* - Create a response tuple that you can hand off to your HTTP server.
136
9c39705 @rustyio Formatting.
rustyio authored
137
8566e10 @rustyio Formatting.
rustyio authored
138 <h3>What modules are involved in a response bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
139
140 * *response_bridge.erl* - The behaviour interface that response bridge modules must implement.
d198fc3 @rustyio Clean up README syntax.
rustyio authored
141 * *response_bridge_wrapper.erl* - A parameterized module that wraps a response.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
142 * *inets_response_bridge.erl* - The response bridge module for Inets.
143 * *mochiweb_response_bridge.erl* - The response bridge module for Mochiweb.
02c9111 @rustyio Update README.
rustyio authored
144 * *???_response_bridge.erl* - Support for more servers on the way.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
145
146 To extend the Simple Bridge to other HTTP servers (or other versions of Inets, Mochiweb, or Yaws),
d15bd36 @rustyio Update README.
rustyio authored
147 copy and modify inets_response_bridge.erl or mochiweb_response_bridge.erl.
Something went wrong with that request. Please try again.