@@ -28,7 +28,18 @@ data Request = Request {
2828 -- depending on backend; in a standalone server setting, this is most likely
2929 -- all information after the domain name. In a CGI application, this would be
3030 -- the information following the path to the CGI executable itself.
31− -- Do not modify this raw value- modify pathInfo instead.
31+ --
32+ -- Middlewares and routing tools should not modify this raw value, as it may
33+ -- be used for such things as creating redirect destinations by applications.
34+ -- Instead, if you are writing a middleware or routing framework, modify the
35+ -- @pathInfo@ instead. This is the approach taken by systems like Yesod
36+ -- subsites.
37+ --
38+ -- /Note/: At the time of writing this documentation, there is at least one
39+ -- system (@Network.Wai.UrlMap@ from @wai-extra@) that does not follow the
40+ -- above recommendation. Therefore, it is recommended that you test the
41+ -- behavior of your application when using @rawPathInfo@ and any form of
42+ -- library that might modify the @Request@.
3243 , rawPathInfo :: B.ByteString
3344 -- | If no query string was specified, this should be empty. This value
3445 -- /will/ include the leading question mark.