diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,3 +1,8 @@ +### 0.3.2.0 + +- Functions and handlers *subrequest* and *subrequestWithRead* were renamed to + *makeSubrequest* and *makeSubrequestWithRead* respectively. + ### 0.3.1.0 - Added function *subrequestWithRead* and an asynchronous variable handler of diff --git a/NgxExport/Tools/Subrequest.hs b/NgxExport/Tools/Subrequest.hs --- a/NgxExport/Tools/Subrequest.hs +++ b/NgxExport/Tools/Subrequest.hs @@ -20,8 +20,8 @@ module NgxExport.Tools.Subrequest ( -- * Making HTTP subrequests -- $makingHTTPSubrequests - subrequest - ,subrequestWithRead + makeSubrequest + ,makeSubrequestWithRead ) where import NgxExport @@ -44,8 +44,8 @@ -- Using asynchronous variable handlers and services together with the HTTP -- client from "Network.HTTP.Client" allows making HTTP subrequests easily. -- This module provides such functionality by exporting asynchronous variable --- handlers __/subrequest/__ and __/subrequestWithRead/__, and functions --- 'subrequest' and 'subrequestWithRead' to build custom handlers. +-- handlers __/makeSubrequest/__ and __/makeSubrequestWithRead/__, and functions +-- 'makeSubrequest' and 'makeSubrequestWithRead' to build custom handlers. -- -- Below is a simple example. -- @@ -62,15 +62,14 @@ -- import Data.ByteString (ByteString) -- import qualified Data.ByteString.Lazy as L -- --- subrequestFromService :: ByteString -> Bool -> IO L.ByteString --- __/subrequestFromService/__ = const . 'subrequest' +-- makeRequest :: ByteString -> Bool -> IO L.ByteString +-- __/makeRequest/__ = const . 'makeSubrequest' -- --- 'ngxExportSimpleService' \'subrequestFromService $ --- 'PersistentService' $ Just $ 'Sec' 10 +-- 'ngxExportSimpleService' \'makeRequest $ 'PersistentService' $ Just $ 'Sec' 10 -- @ -- --- Handler /subrequestFromService/ will be used in a /periodical/ service which --- will retrieve data from a specified URI every 10 seconds. +-- Handler /makeRequest/ will be used in a /periodical/ service which will +-- retrieve data from a specified URI every 10 seconds. -- -- ==== File /nginx.conf/ -- @ @@ -91,7 +90,7 @@ -- server 127.0.0.1:8020; -- } -- --- haskell_run_service __/simpleService_subrequestFromService/__ $hs_service_httpbin +-- haskell_run_service __/simpleService_makeRequest/__ $hs_service_httpbin -- \'{\"uri\": \"http:\/\/httpbin.org\"}\'; -- -- haskell_var_empty_on_error $hs_subrequest; @@ -103,7 +102,7 @@ -- access_log \/tmp\/nginx-test-haskell-access.log; -- -- location \/ { --- haskell_run_async __/subrequest/__ $hs_subrequest +-- haskell_run_async __/makeSubrequest/__ $hs_subrequest -- \'{\"uri\": \"http:\/\/127.0.0.1:8020\/proxy\", -- \"headers\": [[\"Custom-Header\", \"$arg_a\"]]}\'; -- @@ -192,15 +191,16 @@ instance FromJSON SubrequestConf where parseJSON = withObject "SubrequestConf" $ \o -> do - srMethod <- maybe "GET" T.encodeUtf8 <$> o .:? "method" + srMethod <- maybeEmpty $ o .:? "method" srUri <- o .: "uri" - srBody <- maybe "" T.encodeUtf8 <$> o .:? "body" + srBody <- maybeEmpty $ o .:? "body" srHeaders <- map (mk . T.encodeUtf8 *** T.encodeUtf8) <$> o .:? "headers" .!= [] return SubrequestConf {..} + where maybeEmpty = fmap $ maybe "" T.encodeUtf8 -doSubrequest :: SubrequestConf -> IO L.ByteString -doSubrequest SubrequestConf {..} = do +subrequest :: SubrequestConf -> IO L.ByteString +subrequest SubrequestConf {..} = do req <- parseUrlThrow srUri let req' = if B.null srMethod then req @@ -219,8 +219,8 @@ -- | Makes an HTTP request. -- --- This is the core function of the /subrequest/ handler. From perspective of --- an Nginx request, it spawns a subrequest, hence the name. However, this +-- This is the core function of the /makeSubrequest/ handler. From perspective +-- of an Nginx request, it spawns a subrequest, hence the name. However, this -- function can also be used to initiate an original HTTP request from a -- service handler. -- @@ -240,36 +240,38 @@ -- -- Returns the response body if HTTP status of the response is /2xx/, otherwise -- throws an error. To avoid leakage of error messages into variable handlers, --- put the corresponding variables into the list of the directive +-- put the corresponding variables into the list of directive -- /haskell_var_empty_on_error/. -subrequest +makeSubrequest :: ByteString -- ^ Subrequest configuration -> IO L.ByteString -subrequest = maybe (throwIO SubrequestParseError) doSubrequest . +makeSubrequest = maybe (throwIO SubrequestParseError) subrequest . readFromByteStringAsJSON @SubrequestConf -ngxExportAsyncIOYY 'subrequest +ngxExportAsyncIOYY 'makeSubrequest -- | Makes an HTTP request. -- --- Behaves exactly as 'subrequest' except it parses Haskell terms representing --- /SubrequestConf/ with 'read'. +-- Behaves exactly as 'makeSubrequest' except it parses Haskell terms +-- representing /SubrequestConf/ with 'read'. Exported on the Nginx level by +-- handler /makeSubrequestWithRead/. -- -- An example of a subrequest configuration: -- --- > SubrequestConf { srMethod = "GET" +-- > SubrequestConf { srMethod = "" -- > , srUri = "http://127.0.0.1/subreq"} -- > , srBody = "" -- > , srHeaders = [("Header1", "Value1"), ("Header2", "Value2")] -- > } -- -- Notice that unlike JSON parsing, fields of /SubrequestConf/ are not --- omittable and must be listed in the order shown in the example. -subrequestWithRead +-- omittable and must be listed in the order shown in the example. Empty +-- /srMethod/ implies /GET/. +makeSubrequestWithRead :: ByteString -- ^ Subrequest configuration -> IO L.ByteString -subrequestWithRead = maybe (throwIO SubrequestParseError) doSubrequest . +makeSubrequestWithRead = maybe (throwIO SubrequestParseError) subrequest . readFromByteString @SubrequestConf -ngxExportAsyncIOYY 'subrequestWithRead +ngxExportAsyncIOYY 'makeSubrequestWithRead diff --git a/ngx-export-tools-extra.cabal b/ngx-export-tools-extra.cabal --- a/ngx-export-tools-extra.cabal +++ b/ngx-export-tools-extra.cabal @@ -1,5 +1,5 @@ name: ngx-export-tools-extra -version: 0.3.1.0 +version: 0.3.2.0 synopsis: More extra tools for Nginx haskell module description: More extra tools for .