Clone wiki

webmachine / WebmachineUpgrade

Upgrading your application from versions of Webmachine < 1.0

Prior to the 1.0 release of Webmachine, resource functions had a different signature. They went from this:

f(ReqProps, Context) -> {Result, Context}

to this:

f(ReqData, Context) -> {Result, ReqData, Context}

The main difference here is that ReqProps had a handle to a gen_server commonly referred to as Req which was the interface to the request/response data for the resource.

That was reasonably convenient but it meant that many changes to the response occurred by side effect, and also that it was hard to statically determine what elements of the request were needed for a given resource function to perform. These facts made testing less comfortable than we wanted, so we decided it was worth breaking backward compatibility in order to get much greater testability via referential transparency.

Everywhere that an old Webmachine resource used to call a function from the parameterized module returned by ?REQ(ReqProps) it can now instead access or produce a ReqData structure using the wrq module.

A few examples, assuming Req = ?REQ(ReqProps):

Req:get_header_value("content-type")wrq:get_req_header("content-type", ReqData)
Req:get_path_info(foo)wrq:path_info(foo, ReqData)
Req:add_response_header("X-Foo", "foo!")wrq:set_resp_header("X-Foo", "foo!", ReqData)

Note a subtle and important detail about the last of those examples: While the old method actually did the modification for you by side effect, the new way simply returns a new ReqData structure. For this changed structure to have an effect, you must return it in the ReqData portion of your resource function's return tuple.