Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 159 lines (107 sloc) 8.414 kb
652a3d1 @rustyio Merge changes from mrinalwadhwa.
rustyio authored
1 <h1>SimpleBridge</h1>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
2
652a3d1 @rustyio Merge changes from mrinalwadhwa.
rustyio authored
3 SimpleBridge takes the pain out of coding to multiple Erlang HTTP servers by creating a standardized interface. It currently supports Mochiweb, Inets, and Misultin, with Yaws coming soon.
4
5 SimpleBridge is used in the experimental branch of the <a href="http://nitrogenproject.com">The Nitrogen Web Framework</a>.
d15bd36 @rustyio Update README.
rustyio authored
6
7 In a sense, it is similar to <a href="http://github.com/skarab/ewgi">EWGI</a>, except SimpleBridge has some key improvements/differences:
8
e2beb14 @rustyio Formatting.
rustyio authored
9 * <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
10 * <b>Easily extended</b> - Takes about 150 lines to add support for a new HTTP server, vs. ~350 for EWGI.
11 * <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.
12 * <b>Static File Support</b> - Support for sending a static file to the browser, using the underlying HTTP server's own methods.
13 * <b>Cookies Support</b> - SimpleBridge provides interface functions for getting and setting cookies.
e2beb14 @rustyio Formatting.
rustyio authored
14 * <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
15
652a3d1 @rustyio Merge changes from mrinalwadhwa.
rustyio authored
16 SimpleBridge is split into two parts:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
17
d15bd36 @rustyio Update README.
rustyio authored
18 * A *Request Bridge* is a parameterized module that allows you to see information about the incoming request.
19 * A *Response Bridge* is a parameterized module that allows you to construct a response.
20
9c39705 @rustyio Formatting.
rustyio authored
21
aa81244 @rustyio Formatting.
rustyio authored
22 </h2>Hello World Example</h2>
d15bd36 @rustyio Update README.
rustyio authored
23
c022d9d @rustyio More formatting.
rustyio authored
24
57bab9e @rustyio Fix formatting.
rustyio authored
25 % SimpleBridge Hello World Example in Mochiweb
26
27 start(_, _) ->
28 Options = [{ip, "127.0.0.1"}, {port, 8000}],
29 Loop = fun loop/1,
30 mochiweb_http:start([{name, mochiweb_example_app}, {loop, Loop} | Options]).
31
32 loop(Req) ->
33 Request = simple_bridge:make_request(mochiweb_request_bridge, {Req, "./wwwroot"}),
34 HTML = [
35 "&lt;h1&gt;Hello, World!&lt;/h1&gt;",
36 io_lib:format("METHOD: ~p~n&lt;br&gt;&lt;br&gt;", [Request:request_method()]),
37 io_lib:format("COOKIES: ~p~n&lt;br&gt;&lt;br&gt;", [Request:cookies()]),
38 io_lib:format("HEADERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:headers()]),
39 io_lib:format("QUERY PARAMETERS: ~p~n&lt;br&gt;&lt;br&gt;", [Request:query_params()])
40 ],
41
42 Response = simple_bridge:make_response(mochiweb_response_bridge, {Req, "./wwwroot"}),
43 Response1 = Response:status_code(200),
44 Response2 = Response1:header("Content-Type", "text/html"),
45 Response3 = Response2:data(HTML),
46 Response3:build_response().
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
47
48
d198fc3 @rustyio Clean up README syntax.
rustyio authored
49 <h2>Request Bridges</h2>
8566e10 @rustyio Formatting.
rustyio authored
50 <h3>How do I make a request bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
51
c639d63 @rustyio Change interfaces.
rustyio authored
52 To make a request bridge for an incoming request, call the simple_bridge:make_request/2 function,
d15bd36 @rustyio Update README.
rustyio authored
53 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
54
d198fc3 @rustyio Clean up README syntax.
rustyio authored
55 Inets example:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
56
d15bd36 @rustyio Update README.
rustyio authored
57 RequestBridge = simple_bridge:make_request(inets_response_bridge, Info)
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
58
d198fc3 @rustyio Clean up README syntax.
rustyio authored
59 Mochiweb example:
60
d15bd36 @rustyio Update README.
rustyio authored
61 RequestBridge = simple_bridge:make_request(mochiweb_response_bridge, [{Req, Docroot}]).
62
63
8566e10 @rustyio Formatting.
rustyio authored
64 <h3>What can I do with the request bridge object?</h3>
d198fc3 @rustyio Clean up README syntax.
rustyio authored
65
d15bd36 @rustyio Update README.
rustyio authored
66 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
67
9c39705 @rustyio Formatting.
rustyio authored
68
8566e10 @rustyio Formatting.
rustyio authored
69 <h3>Request Bridge Interface</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
70
71 * *Bridge:request_method()* - returns 'GET', 'POST', 'HEAD', etc.
72 * *Bridge:path()* - returns the requested path and file.
73 * *Bridge:peer_ip()* - returns the client's IP address in tuple format (74.125.67.100 = {74, 125, 67, 100})
74 * *Bridge:peer_port()* - returns the client's port.
d15bd36 @rustyio Update README.
rustyio authored
75 * *Bridge:headers()* - returns a proplist of headers, [{header1, "Value1"}, {header2, "Value2"}, ...]
76 * *Bridge:header(Header)* - returns the value of a header.
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
77 * *Bridge:cookies()* - returns a proplist of cookies, [{"Cookie1", "Value1"}, {"Cookie2", "Value2"}, ...]
78 * *Bridge:query_params()* - returns a proplist of query params, [{"Query1", "Value1"}, {"Query2", "Value2"}, ...]
d15bd36 @rustyio Update README.
rustyio authored
79 * *Bridge:post_params()* - returns a proplist of post params, [{"Post1", "Value1"}, {"Post2", "Value2"}, ...]
80 * *Bridge:post_files()* - returns a list of upload_file records, describing the files uploaded in a multipart post.
81 * *Bridge:request_body()* - returns the request body that has been read so far, as a list.
82 * *Bridge:error()* - returns an Erlang term describing any errors that happened while parsing a multipart post.
57bab9e @rustyio Fix formatting.
rustyio authored
83
9c39705 @rustyio Formatting.
rustyio authored
84
8566e10 @rustyio Formatting.
rustyio authored
85 <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
86
87 * *request_bridge.erl* - The behaviour interface that request bridge modules must implement.
d198fc3 @rustyio Clean up README syntax.
rustyio authored
88 * *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
89 * *inets_request_bridge.erl* - The request bridge module for Inets.
90 * *mochiweb_request_bridge.erl* - The request bridge module for Mochiweb.
2b7aa18 @choptastic Update readme
choptastic authored
91 * *webmachine_request_bridge.erl* - The request bridge module for Webmachine.
92 * *cowboy_request_bridge.erl* - The request bridge module for Cowboy.
93 * *yaws_request_bridge.erl* - The request bridge module for Yaws.
94 * *misultin_request_bridge.erl* - The request bridge module for Misultin.
d15bd36 @rustyio Update README.
rustyio authored
95 * *???_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
96
652a3d1 @rustyio Merge changes from mrinalwadhwa.
rustyio authored
97 To extend the SimpleBridge 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
98
9c39705 @rustyio Formatting.
rustyio authored
99
d198fc3 @rustyio Clean up README syntax.
rustyio authored
100 <h2>Response Bridges</h2>
8566e10 @rustyio Formatting.
rustyio authored
101 <h3>How do I make a response bridge?</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
102
d15bd36 @rustyio Update README.
rustyio authored
103 To make a request bridge for an incoming request, call the simple_bridge:make_response/2 function,
104 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
105
d198fc3 @rustyio Clean up README syntax.
rustyio authored
106 Inets example:
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
107
57bab9e @rustyio Fix formatting.
rustyio authored
108 ResponseBridge = simple_bridge:make_response(inets_response_bridge, Info)
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
109
d198fc3 @rustyio Clean up README syntax.
rustyio authored
110 Mochiweb example:
111
57bab9e @rustyio Fix formatting.
rustyio authored
112 ResponseBridge = simple_bridge:make_response(mochiweb_response_bridge, {Req, Docroot})
d198fc3 @rustyio Clean up README syntax.
rustyio authored
113
9c39705 @rustyio Formatting.
rustyio authored
114
8566e10 @rustyio Formatting.
rustyio authored
115 <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
116
d15bd36 @rustyio Update README.
rustyio authored
117 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
118
119 Each function below returns a new bridge object, so your will need to
120 chain together requests like this:
121
d15bd36 @rustyio Update README.
rustyio authored
122 Bridge = simple_bridge:make_response(inets_response_bridge, Info),
d198fc3 @rustyio Clean up README syntax.
rustyio authored
123 Bridge1 = Bridge:status_code(200),
124 Bridge2 = Bridge1:header("Header1", "Value1"),
d15bd36 @rustyio Update README.
rustyio authored
125 Bridge3 = Bridge2:data(HTML),
d198fc3 @rustyio Clean up README syntax.
rustyio authored
126 etc.
d15bd36 @rustyio Update README.
rustyio authored
127
9c39705 @rustyio Formatting.
rustyio authored
128
8566e10 @rustyio Formatting.
rustyio authored
129 <h3>Response Bridge Interface</h3>
951cc9d @rustyio Finish unit tests for Inets Request. Implement Inets Response. Add unit ...
rustyio authored
130
131 * *Bridge:status_code(Code)* - set the HTTP status code. (200, 404, etc.)
132 * *Bridge:header(Name, Value)* - set an HTTP header.
133 * *Bridge:clear_headers()* - clear all previously set headers.
134 * *Bridge:cookie(Name, Value)* - set a cookie for path "/" with expiration in 20 minutes.
135 * *Bridge:cookie(Name, Value, Path, Exp)* - Set a cookie. Exp is an integer in minutes.
136 * *Bridge:clear_cookies()* - clear all previously set cookies.
137 * *Bridge:data(Data)* - set the data to return in the response. Usually HTML goes here.
d15bd36 @rustyio Update README.
rustyio authored
138 * *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
139
140 Finally, you build the response to send to your HTTP server with the build_response/0 function.
141
142 * *Bridge:build_response()* - Create a response tuple that you can hand off to your HTTP server.
143
9c39705 @rustyio Formatting.
rustyio authored
144
8566e10 @rustyio Formatting.
rustyio authored
145 <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
146
147 * *response_bridge.erl* - The behaviour interface that response bridge modules must implement.
d198fc3 @rustyio Clean up README syntax.
rustyio authored
148 * *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
149 * *inets_response_bridge.erl* - The response bridge module for Inets.
150 * *mochiweb_response_bridge.erl* - The response bridge module for Mochiweb.
2b7aa18 @choptastic Update readme
choptastic authored
151 * *webmachine_response_bridge.erl* - The response bridge module for Webmachine.
152 * *cowboy_response_bridge.erl* - The response bridge module for Cowboy.
153 * *yaws_response_bridge.erl* - The response bridge module for Yaws.
154 * *misultin_response_bridge.erl* - The response bridge module for Misultin.
02c9111 @rustyio Update README.
rustyio authored
155 * *???_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
156
652a3d1 @rustyio Merge changes from mrinalwadhwa.
rustyio authored
157 To extend the SimpleBridge to other HTTP servers (or other versions of Inets, Mochiweb, or Yaws),
d15bd36 @rustyio Update README.
rustyio authored
158 copy and modify inets_response_bridge.erl or mochiweb_response_bridge.erl.
Something went wrong with that request. Please try again.