Justin Sheehy avatar Justin Sheehy committed ae65aaf

Automated commit message

Comments (0)

Files changed (1)

WebmachineMechanics.wiki

-== How does this Webmachine thing work, anyway? ==
-
-This page documents the basic mechanics of Webmachine from the point of view of a single incoming HTTP Request, documenting the behavior of Webmachine through to the HTTP Response.
-
-(This is a bit different from what you might get with a "Web Framework" as we're not going to talk about MVC, ORMs, or anything else about the rest of the shape of your application.  We believe that you know better than we do how to structure your own app -- Webmachine's job is to make sure that your app's presence on the Web is well-behaved and well-structured.)
-
-When a request is initially received by Webmachine it is handled by the [[DispatchConfiguration|dispatcher]].  If the dispatcher does not find a matching resource then it will immediately respond with a 404 Not Found.  If a match is found then a [[WebmachineReqData|request data record]] is created and the matching [[WebmachineResources|resource]] is kicked off via its {{{ init/1 }}} function.
-
-The resource then flows through the decision core, which is effectively just running the request through the [[BigHTTPGraph|HTTP flowchart]].  At each decision point (diamond) in the diagram, Webmachine will determine which path to follow.  In some cases it can determine the path purely from the request data -- for instance, the path from decision {{{ C3 }}} depends purely on whether the client sent an {{{ Accept }}} header.  In many cases, however, the decision is application-specific -- the path from {{{ B10 }}} depends on the value the [[WebmachineResources|resource]] returns from {{{ allowed_methods.}}}  Eventually the chosen path will terminate at one of the rectangles on the diagram.  At that point Webmachine will send an appropriate HTTP response, with the headers and body dependent on the path through the diagram and the values returned by the resource's functions.
-
-Most of the time you don't need to worry about this big diagram, though -- just define the [[WebmachineResources|resource functions]] relevant to your app and Webmachine will do the rest.  A good understanding of this central mechanism in Webmachine is most useful when [[WebmachineDebugging|debugging your resources]].
-
-From the way that webmachine's decision core works, it follows that Webmachine's HTTP behavior is transactional.  Each HTTP Request is fully received, and the resulting HTTP Response is then fully constructed before being returned.  This means that while Webmachine is suitable for a great many Web applications it is not a good fit for (e.g.) an application that will gradually or continuously stream responses back to clients.
-
-A useful way to build Webmachine applications is often just to write a single function such as {{{ to_html }}} to provide the most basic of stubs; when that function (or any other returned by {{{content_types_provided}}}) you can produce {{{200 OK}}} responses.  After that, you can easily extend your application's Web behavior simply by filling in the other [[WebmachineResources|resource functions]] as desired.
+== How does this Webmachine thing work, anyway? ==
+
+This page documents the basic mechanics of Webmachine from the point of view of a single incoming HTTP Request, documenting the behavior of Webmachine through to the HTTP Response.
+
+(This is a bit different from what you might get with a "Web Framework" as we're not going to talk about MVC, ORMs, or anything else about the rest of the shape of your application.  We believe that you know better than we do how to structure your own app -- Webmachine's job is to make sure that your app's presence on the Web is well-behaved and well-structured.)
+
+When a request is initially received by Webmachine it is handled by the [[DispatchConfiguration|dispatcher]].  If the dispatcher does not find a matching resource then it will immediately respond with a 404 Not Found.  If a match is found then a [[WebmachineReqData|request data record]] is created and the matching [[WebmachineResources|resource]] is kicked off via its {{{ init/1 }}} function.
+
+The resource then flows through the decision core, which is effectively just running the request through the [[BigHTTPGraph|HTTP flowchart]].  At each decision point (diamond) in the diagram, Webmachine will determine which path to follow.  In some cases it can determine the path purely from the request data -- for instance, the path from decision {{{ C3 }}} depends purely on whether the client sent an {{{ Accept }}} header.  In many cases, however, the decision is application-specific -- the path from {{{ B10 }}} depends on the value the [[WebmachineResources|resource]] returns from {{{ allowed_methods.}}}  Eventually the chosen path will terminate at one of the rectangles on the diagram.  At that point Webmachine will send an appropriate HTTP response, with the headers and body dependent on the path through the diagram and the values returned by the resource's functions.
+
+Most of the time you don't need to worry about this big diagram, though -- just define the [[WebmachineResources|resource functions]] relevant to your app and Webmachine will do the rest.  A good understanding of this central mechanism in Webmachine is most useful when [[WebmachineDebugging|debugging your resources]].
+
+From the way that webmachine's decision core works, it follows that Webmachine's HTTP behavior is transactional.  Each HTTP Request is fully received, and the resulting HTTP Response is then fully constructed before being returned.  This means that while Webmachine is suitable for a great many Web applications it is not a good fit for an application that will gradually or continuously stream responses back to clients inside the context of a single HTTP Request.
+
+A useful way to build Webmachine applications is often just to write a single function such as {{{ to_html }}} to provide the most basic of stubs; when that function (or any other returned by {{{content_types_provided}}}) you can produce {{{200 OK}}} responses.  After that, you can easily extend your application's Web behavior simply by filling in the other [[WebmachineResources|resource functions]] as desired.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.