@@ -2,10 +2,38 @@
22{-# LANGUAGE CPP #-}
33
44module Network.Wai.Middleware.Rewrite
5− ( rewrite
6− , rewritePure
5+ ( -- * How to use this module
6+ -- $howto
7+
8+ -- ** A note on semantics
9+
10+ -- $semantics
11+
12+ -- ** Paths and Queries
13+
14+ -- $pathsandqueries
15+ PathsAndQueries
16+
17+ -- ** An example rewriting paths with queries
18+
19+ -- $takeover
20+
21+ -- ** Upgrading from wai-extra ≤ 3.0.16.1
22+
23+ -- $upgrading
24+
25+ -- * 'Middleware'
26+
27+ -- ** Recommended functions
728 , rewriteWithQueries
829 , rewritePureWithQueries
30+
31+ -- ** Deprecated
32+ , rewrite
33+ , rewritePure
34+
35+ -- * Operating on 'Request's
36+
937 , rewriteRequest
1038 , rewriteRequestPure
1139 ) where
@@ -23,57 +51,217 @@ import Network.HTTP.Types as H
2351import Control.Applicative
2452#endif
2553
26−-- | A tuple of the path sections as '[Text]' and query parameters as
27−-- 'H.QueryText'.
54+-- $howto
55+-- This module provides 'Middleware' to rewrite URL paths. It also provides
56+-- functions that will convert a 'Request' to a modified 'Request'.
57+-- Both operations require a function that takes URL parameters and
58+-- headers, and returns new URL parameters. Parameters are pieces of URL
59+-- paths and query parameters.
60+--
61+-- If you are a new user of the library, use 'rewriteWithQueries' or
62+-- 'rewritePureWithQueries' for middleware. For modifying 'Request's
63+-- directly, use 'rewriteRequest' or 'rewriteRequestPure'.
64+
65+-- $semantics
66+--
67+-- Versions of this library in wai-extra ≤ 3.0.16.1 exported only
68+-- 'rewrite' and 'rewritePure' and both modified 'rawPathInfo' of the
69+-- underlying requests. Such modification has been proscribed. The
70+-- semantics of these functions have not changed; instead the recommended
71+-- approach is to use 'rewriteWithQueries' and 'rewritePureWithQueries'.
72+-- The new functions are slightly different, as described in the section
73+-- on upgrading; code for previous library versions can be upgraded with
74+-- a single change, and as the type of the new function is different the
75+-- compiler will indicate where this change must be made.
76+--
77+-- The 'rewriteRequest' and 'rewriteRequestPure' functions use the new
78+-- semantics, too.
79+
80+-- $pathsandqueries
81+--
82+-- This library defines the type synonym `PathsAndQueries` to make code
83+-- handling paths and queries easier to read.
84+--
85+-- /e.g./ /\/foo\/bar/ would look like
86+--
87+-- > ["foo", "bar"] :: Text
88+--
89+-- /?bar=baz/ would look like
90+--
91+-- > [("bar", Just "baz")] :: QueryText
92+--
93+-- Together,
94+--
95+-- /\/foo?bar=baz/ would look like
96+--
97+-- > (["foo"],[("bar", Just "baz")]) :: PathsAndQueries
98+
99+-- $takeover
100+-- Let’s say we want to replace a website written in PHP with one written
101+-- using WAI. We’ll use the
102+-- <https://hackage.haskell.org/package/http-reverse-proxy http-reverse-proxy>
103+-- package to serve the old
104+-- site from the new site, but there’s a problem. The old site uses pages like
105+--
106+-- @
107+-- index.php?page=/page/
108+-- @
109+--
110+-- whereas the new site would look like
111+--
112+-- @
113+-- index\//page/
114+-- @
115+--
116+-- In doing this, we want to separate the migration code from our new
117+-- website. So we’d like to handle links internally using the path
118+-- formulation, but externally have the old links still work.
119+--
120+-- Therefore, we will use middleware ('rewritePureWithQueries') from this
121+-- module to rewrite incoming requests from the query formulation to the
122+-- paths formulation.
123+--
124+-- > {-# LANGUAGE ViewPatterns #-}
125+-- >
126+-- > rewritePathFromPhp :: Middleware
127+-- > rewritePathFromPhp = rewritePureWithQueries pathFromPhp
128+-- >
129+-- > pathFromPhp :: PathsAndQueries -> RequestHeaders -> PathsAndQueries
130+-- > pathFromPhp (pieces, queries) _ = piecesConvert pieces queries
131+-- > where
132+-- > piecesConvert :: [Text] -> QueryText -> PathsAndQueries
133+-- > piecesConvert ["index.php"] qs@(join . lookup "page" -> Just page) =
134+-- > ( ["index", page]
135+-- > , delete ("page", pure page) qs
136+-- > )
137+-- > piecesConvert ps qs = (ps, qs)
138+--
139+-- On the other side, we will use 'rewriteRequestPure' to rewrite outgoing
140+-- requests to the original website from the reverse proxy code (using the
141+-- 'Network.HTTP.ReverseProxy.WPRModifiedRequest' or
142+-- 'Network.HTTP.ReverseProxy.WPRModifiedRequestSecure' constructors. Note,
143+-- these links will only work if the haddock documentation for
144+-- <https://hackage.haskell.org/package/http-reverse-proxy http-reverse-proxy>
145+-- is installed).
146+--
147+-- > rewritePhpFromPath :: Request -> Request
148+-- > rewritePhpFromPath = rewriteRequestPure phpFromPath
149+-- >
150+-- > phpFromPath :: PathsAndQueries -> RequestHeaders -> PathsAndQueries
151+-- > phpFromPath (pieces, queries) _ = piecesConvert pieces queries
152+-- > where
153+-- > piecesConvert :: [Text] -> QueryText -> PathsAndQueries
154+-- > piecesConvert ("index":page:[]) qs = ( ["index.php"], ("page", pure page) : qs )
155+-- > piecesConvert ps qs = (ps, qs)
156+--
157+-- For the whole example, see
158+-- <https://gist.github.com/dbaynard/c844d0df124f68ec8b6da152c581ce6d>.
159+
160+-- $upgrading
161+-- It is quite simple to upgrade from 'rewrite' and 'rewritePure', to
162+-- 'rewriteWithQueries' and 'rewritePureWithQueries'.
163+-- Insert 'Data.Bifunctor.first', which specialises to
164+--
165+-- @
166+-- 'Data.Bifunctor.first' :: (['Text'] -> ['Text']) -> 'PathsAndQueries' -> 'PathsAndQueries'
167+-- @
168+--
169+-- as the following example demonstrates.
170+--
171+-- Old versions of the libary could only handle path pieces, not queries.
172+-- This could have been supplied to 'rewritePure'.
173+--
174+-- @
175+-- staticConvert' :: [Text] -> H.RequestHeaders -> [Text]
176+-- staticConvert' pieces _ = piecesConvert pieces
177+-- where
178+-- piecesConvert [] = ["static", "html", "pages.html"]
179+-- piecesConvert route@("pages":_) = "static":"html":route
180+-- @
181+--
182+-- Instead, use this function, supplied to 'rewritePureWithQueries'.
183+--
184+-- @
185+-- staticConvert :: 'PathsAndQueries' -> H.RequestHeaders -> 'PathsAndQueries'
186+-- staticConvert pathsAndQueries _ = 'Data.Bifunctor.first' piecesConvert pathsAndQueries
187+-- where
188+-- piecesConvert [] = ["static", "html", "pages.html"]
189+-- piecesConvert route@("pages":_) = "static":"html":route
190+-- @
191+--
192+-- The former formulation is deprecated for two reasons:
193+--
194+-- 1. The original formulation of 'rewrite' modified 'rawPathInfo', which
195+-- is deprecated behaviour.
196+--
197+-- 2. The original formulation did not allow query parameters to
198+-- influence the path.
199+--
200+-- Concerning the first point, take care with semantics of your program when
201+-- upgrading as the upgraded functions no longer modify 'rawPathInfo'.
202+
203+--------------------------------------------------
204+-- * Types
205+--------------------------------------------------
206+
207+-- | A tuple of the path sections as ['Text'] and query parameters as
208+-- 'H.QueryText'. This makes writing type signatures for the conversion
209+-- function far more pleasant.
28210type PathsAndQueries = ([Text], H.QueryText)
29211
30−-- | rewrite based on your own conversion rules
212+--------------------------------------------------
213+-- * Rewriting 'Middleware'
214+--------------------------------------------------
215+
216+-- | Rewrite based on your own conversion function for paths only, to be
217+-- supplied by users of this library (with the conversion operating in 'IO').
218+--
219+-- For new code, use 'rewriteWithQueries' instead.
31220rewrite :: ([Text] -> H.RequestHeaders -> IO [Text]) -> Middleware
32221rewrite convert app req sendResponse = do
33222 let convertIO = pathsOnly . curry $ liftIO . uncurry convert
34223 newReq <- rewriteRequestRawM convertIO req
35224 app newReq sendResponse
225+{-# WARNING rewrite [
226+ "This modifies the 'rawPathInfo' field of a 'Request'."
227+ , " This is not recommended behaviour; it is however how"
228+ , " this function has worked in the past."
229+ , " Use 'rewriteWithQueries' instead"] #-}
36230
37−-- | rewrite based on your own conversion rules
38−-- Example convert function:
39−
40−-- staticConvert :: [Text] -> H.RequestHeaders -> [Text]
41−-- staticConvert pieces _ = piecesConvert pieces
42−-- where
43−-- piecesConvert [] = ["static", "html", "pages.html"]
44−-- piecesConvert route@("pages":_) = "static":"html":route
231+-- | Rewrite based on pure conversion function for paths only, to be
232+-- supplied by users of this library.
233+--
234+-- For new code, use 'rewritePureWithQueries' instead.
45235rewritePure :: ([Text] -> H.RequestHeaders -> [Text]) -> Middleware
46236rewritePure convert app req =
47237 let convertPure = pathsOnly . curry $ Identity . uncurry convert
48238 newReq = runIdentity $ rewriteRequestRawM convertPure req
49239 in app newReq
240+{-# WARNING rewritePure [
241+ "This modifies the 'rawPathInfo' field of a 'Request'."
242+ , " This is not recommended behaviour; it is however how"
243+ , " this function has worked in the past."
244+ , " Use 'rewritePureWithQueries' instead"] #-}
50245
51−-- | rewrite based on your own conversion rules
52−-- Example convert function:
53−
54−-- staticConvert :: [Text] -> H.RequestHeaders -> [Text]
55−-- staticConvert pieces _ = piecesConvert pieces
56−-- where
57−-- piecesConvert [] = ["static", "html", "pages.html"]
58−-- piecesConvert route@("pages":_) = "static":"html":route
246+-- | Rewrite based on your own conversion function for paths and queries.
247+-- This function is to be supplied by users of this library, and operates
248+-- in 'IO'.
59249rewriteWithQueries :: (PathsAndQueries -> H.RequestHeaders -> IO PathsAndQueries)
60250 -> Middleware
61251rewriteWithQueries convert app req sendResponse = do
62252 newReq <- rewriteRequestM convert req
63253 app newReq sendResponse
64254
65−-- | rewrite based on your own conversion rules
66−-- Example convert function:
67−
68−-- staticConvert :: [Text] -> H.RequestHeaders -> [Text]
69−-- staticConvert pieces _ = piecesConvert pieces
70−-- where
71−-- piecesConvert [] = ["static", "html", "pages.html"]
72−-- piecesConvert route@("pages":_) = "static":"html":route
255+-- | Rewrite based on pure conversion function for paths and queries. This
256+-- function is to be supplied by users of this library.
73257rewritePureWithQueries :: (PathsAndQueries -> H.RequestHeaders -> PathsAndQueries)
74258 -> Middleware
75259rewritePureWithQueries convert app req = app $ rewriteRequestPure convert req
76260
261+--------------------------------------------------
262+-- * Modifying 'Request's directly
263+--------------------------------------------------
264+
77265-- | Modify a 'Request' using the supplied function in 'IO'. This is suitable for
78266-- the reverse proxy example.
79267rewriteRequest :: (PathsAndQueries -> H.RequestHeaders -> IO PathsAndQueries)
@@ -90,6 +278,10 @@ rewriteRequestPure convert req =
90278 let convertPure = curry $ Identity . uncurry convert
91279 in runIdentity $ rewriteRequestRawM convertPure req
92280
281+--------------------------------------------------
282+-- * Helper functions
283+--------------------------------------------------
284+
93285-- | This helper function factors out the common behaviour of rewriting requests.
94286rewriteRequestM :: (Applicative m, Monad m)
95287 => (PathsAndQueries -> H.RequestHeaders -> m PathsAndQueries)
@@ -97,12 +289,10 @@ rewriteRequestM :: (Applicative m, Monad m)
97289rewriteRequestM convert req = do
98290 (pInfo, qText) <- curry convert (pathInfo req) (H.queryToQueryText . queryString $ req) (requestHeaders req)
99291 pure req {pathInfo = pInfo, queryString = H.queryTextToQuery qText}
100− -- rawPInfo = toS . toLazyByteString $ encodePathSegmentsRelative pInfo
101− -- rawQString = toS . toLazyByteString $ renderQueryText True qText
102292
103−-- | This helper function preserves the semantics of wai-extra <= 3.0, in
104−-- which the rewrite functions modify the `rawPathInfo` parameter. Note
105−-- that this has not been extended to modify the `rawQueryInfo` as
293+-- | This helper function preserves the semantics of wai-extra ≤ 3.0, in
294+-- which the rewrite functions modify the 'rawPathInfo' parameter. Note
295+-- that this has not been extended to modify the 'rawQueryInfo' as
106296-- modifying either of these values has been deprecated.
107297rewriteRequestRawM :: (Applicative m, Monad m)
108298 => (PathsAndQueries -> H.RequestHeaders -> m PathsAndQueries)
@@ -111,11 +301,18 @@ rewriteRequestRawM convert req = do
111301 newReq <- rewriteRequestM convert req
112302 let rawPInfo = TE.encodeUtf8 . T.intercalate "/" . pathInfo $ newReq
113303 pure newReq { rawPathInfo = rawPInfo }
304+{-# WARNING rewriteRequestRawM [
305+ "This modifies the 'rawPathInfo' field of a 'Request'."
306+ , " This is not recommended behaviour; it is however how"
307+ , " this function has worked in the past."
308+ , " Use 'rewriteRequestM' instead"] #-}
114309
115−-- | Produce a function that works on 'PathsandQueries' from one working
116−-- only on paths.
310+-- | Produce a function that works on 'PathsAndQueries' from one working
311+-- only on paths. This is not exported, as it is only needed to handle
312+-- code written for versions ≤ 3.0 of the library; see the
313+-- example above using 'Data.Bifunctor.first' to do something similar.
117314pathsOnly :: (Applicative m, Monad m)
118315 => ([Text] -> H.RequestHeaders -> m [Text])
119316 -> PathsAndQueries -> H.RequestHeaders -> m PathsAndQueries
120−pathsOnly convert paths headers = (,[]) <$> convert (fst paths) headers
317+pathsOnly convert psAndQs headers = (,[]) <$> convert (fst psAndQs) headers
121318{-# INLINE pathsOnly #-}