Copyright | (c) Alexey Radkov 2016-2023 |
---|---|
License | BSD-style |
Maintainer | alexey.radkov@gmail.com |
Stability | stable |
Portability | non-portable (requires POSIX and Template Haskell) |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Nginx / Haskell interoperability layer and exporters of regular Haskell functions at Nginx level for using in configuration directives of nginx-haskell-module.
Synopsis
- type ContentHandlerResult = (ByteString, ByteString, Int, HTTPHeaders)
- type UnsafeContentHandlerResult = (ByteString, ByteString, Int)
- type HTTPHeaders = [(ByteString, ByteString)]
- ngxExportSS :: Name -> Q [Dec]
- ngxExportSSS :: Name -> Q [Dec]
- ngxExportSLS :: Name -> Q [Dec]
- ngxExportBS :: Name -> Q [Dec]
- ngxExportBSS :: Name -> Q [Dec]
- ngxExportBLS :: Name -> Q [Dec]
- ngxExportYY :: Name -> Q [Dec]
- ngxExportBY :: Name -> Q [Dec]
- ngxExportIOYY :: Name -> Q [Dec]
- ngxExportAsyncIOYY :: Name -> Q [Dec]
- ngxExportAsyncOnReqBody :: Name -> Q [Dec]
- ngxExportServiceIOYY :: Name -> Q [Dec]
- ngxExportHandler :: Name -> Q [Dec]
- ngxExportDefHandler :: Name -> Q [Dec]
- ngxExportUnsafeHandler :: Name -> Q [Dec]
- ngxExportAsyncHandler :: Name -> Q [Dec]
- ngxExportAsyncHandlerOnReqBody :: Name -> Q [Dec]
- ngxExportServiceHook :: Name -> Q [Dec]
- ngxCyclePtr :: IO (Ptr ())
- ngxUpstreamMainConfPtr :: IO (Ptr ())
- ngxCachedTimePtr :: IO (Ptr (Ptr ()))
- ngxCachedPid :: IO CPid
- newtype TerminateWorkerProcess = TerminateWorkerProcess String
- newtype RestartWorkerProcess = RestartWorkerProcess String
- data WorkerProcessIsExiting
- data FinalizeHTTPRequest = FinalizeHTTPRequest Int (Maybe String)
- newtype CInt = CInt Int32
- newtype CUInt = CUInt Word32
Type declarations
type ContentHandlerResult = (ByteString, ByteString, Int, HTTPHeaders) Source #
The 4-tuple contains (content, content-type, HTTP-status, response-headers).
type UnsafeContentHandlerResult = (ByteString, ByteString, Int) Source #
The 3-tuple contains (content, content-type, HTTP-status).
Both the content and the content-type are supposed to be referring to low-level string literals that do not need to be freed upon an HTTP request termination and must not be garbage-collected in the Haskell RTS.
type HTTPHeaders = [(ByteString, ByteString)] Source #
A list of HTTP headers comprised of name-value pairs.
Exporters
Nginx Haskell module aims at bringing regular Haskell code into Nginx
configuration. A special sort of functions to accomplish this is called
exporters. An exporter accepts a Name
of an exported Haskell function
(also called handler) and generates appropriate FFI code.
Exporters export Haskell handlers of a few types:
- synchronous handlers,
- asynchronous handlers,
- services (which are asynchronous handlers that run in background),
- synchronous content handlers,
- asynchronous content handlers,
- synchronous service hooks.
Exporters accept handlers only of certain types. For example, exporter
ngxExportSS
accepts only functions of type String -> String.
Below is a simple example featuring synchronous handlers.
File test.hs
{-# LANGUAGE TemplateHaskell #-} module Test where import NgxExport import qualified Data.Char as C toUpper :: String -> String toUpper = map C.toUpperngxExportSS
'toUpperngxExportSS
'reverse isInList :: [String] -> Bool isInList [] = False isInList (x : xs) = x `elem` xsngxExportBLS
'isInList
In this module, we declared three synchronous handlers: toUpper, reverse, and isInList. Handler reverse exports function reverse from Prelude which reverses lists.
File nginx.conf
user nginx; worker_processes 4; events { worker_connections 1024; } http { default_type application/octet-stream; sendfile on; haskell load /var/lib/nginx/test.so; server { listen 8010; server_name main; location / { haskell_run toUpper $hs_upper $arg_u; haskell_run reverse $hs_reverse $arg_r; haskell_run isInList $hs_isInList $arg_a $arg_b $arg_c $arg_d; echo "toUpper $arg_u = $hs_upper"; echo "reverse $arg_r = $hs_reverse"; echo "$arg_a `isInList` [$arg_b, $arg_c, $arg_d] = $hs_isInList"; } } }
A simple test
$ curl 'http://127.0.0.1:8010/?u=hello&r=world&a=1&b=10&c=1' toUpper hello = HELLO reverse world = dlrow 1 `isInList` [10, 1, ] = 1
Synchronous handlers
Asynchronous handlers and services
ngxExportAsyncOnReqBody :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->ByteString
->IO
ByteString
for using in directive haskell_run_async_on_request_body.
The first argument of the exported function contains buffers of the client request body.
ngxExportServiceIOYY :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->Bool
->IO
ByteString
for using in directives haskell_run_service and haskell_service_var_update_callback.
The boolean argument of the exported function marks that the service is being run for the first time.
Content handlers
ngxExportHandler :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->ContentHandlerResult
for using in directives haskell_content and haskell_static_content.
ngxExportDefHandler :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->ByteString
for using in directives haskell_content and haskell_static_content.
ngxExportUnsafeHandler :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->UnsafeContentHandlerResult
for using in directive haskell_unsafe_content.
ngxExportAsyncHandler :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->IO
ContentHandlerResult
for using in directive haskell_async_content.
ngxExportAsyncHandlerOnReqBody :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->ByteString
->IO
ContentHandlerResult
for using in directive haskell_async_content_on_request_body.
The first argument of the exported function contains buffers of the client request body.
Service hooks
ngxExportServiceHook :: Name -> Q [Dec] Source #
Exports a function of type
ByteString
->IO
ByteString
for using in directives haskell_service_hook and haskell_service_update_hook.
Accessing Nginx global objects
Opaque pointers
ngxCyclePtr :: IO (Ptr ()) Source #
Returns an opaque pointer to the Nginx cycle object for using it in C plugins.
The actual type of the returned pointer is
ngx_cycle_t *
(the value of argument cycle in the worker's initialization function).
ngxUpstreamMainConfPtr :: IO (Ptr ()) Source #
Returns an opaque pointer to the Nginx upstream main configuration for using it in C plugins.
The actual type of the returned pointer is
ngx_http_upstream_main_conf_t *
(the value of expression
ngx_http_cycle_get_module_main_conf(cycle, ngx_http_upstream_module)
in
the worker's initialization function).
ngxCachedTimePtr :: IO (Ptr (Ptr ())) Source #
Returns an opaque pointer to the Nginx cached time object for using it in C plugins.
The actual type of the returned pointer is
volatile ngx_time_t **
(the address of the Nginx global variable ngx_cached_time).
Be aware that time gotten from this pointer is not reliable in asynchronous tasks and services as soon as it gets updated only when some event happens inside the Nginx worker to which the task is bound and thus can be heavily outdated.
Primitive objects
ngxCachedPid :: IO CPid Source #
Returns the PID of the current worker process cached in Nginx.
Since: 1.7.1
Accessing Nginx core functionality from Haskell handlers
newtype TerminateWorkerProcess Source #
Terminates the worker process.
Being thrown from a service, this exception makes Nginx log the supplied message and terminate the worker process without respawning. This can be useful when the service is unable to read its configuration from the Nginx configuration script or to perform an important initialization action.
Since: 1.6.2
TerminateWorkerProcess String | Contains the message to log |
Instances
Exception TerminateWorkerProcess Source # | |
Defined in NgxExport | |
Show TerminateWorkerProcess Source # | |
Defined in NgxExport showsPrec :: Int -> TerminateWorkerProcess -> ShowS # show :: TerminateWorkerProcess -> String # showList :: [TerminateWorkerProcess] -> ShowS # | |
Eq TerminateWorkerProcess Source # | |
Defined in NgxExport |
newtype RestartWorkerProcess Source #
Restarts the worker process.
The same as TerminateWorkerProcess
, except that a new worker process shall
be spawned by the Nginx master process in place of the current one.
Since: 1.6.3
RestartWorkerProcess String | Contains the message to log |
Instances
Exception RestartWorkerProcess Source # | |
Defined in NgxExport | |
Show RestartWorkerProcess Source # | |
Defined in NgxExport showsPrec :: Int -> RestartWorkerProcess -> ShowS # show :: RestartWorkerProcess -> String # showList :: [RestartWorkerProcess] -> ShowS # | |
Eq RestartWorkerProcess Source # | |
Defined in NgxExport (==) :: RestartWorkerProcess -> RestartWorkerProcess -> Bool # (/=) :: RestartWorkerProcess -> RestartWorkerProcess -> Bool # |
data WorkerProcessIsExiting Source #
Signals that the worker process is exiting.
This asynchronous exception is thrown from the Nginx core to all services
with cancelWith
when the working process is exiting. An exception handler
that catches this exception is expected to perform the service's specific
cleanup and finalization actions.
Since: 1.6.4
Instances
Exception WorkerProcessIsExiting Source # | |
Defined in NgxExport | |
Show WorkerProcessIsExiting Source # | |
Defined in NgxExport showsPrec :: Int -> WorkerProcessIsExiting -> ShowS # show :: WorkerProcessIsExiting -> String # showList :: [WorkerProcessIsExiting] -> ShowS # | |
Eq WorkerProcessIsExiting Source # | |
Defined in NgxExport |
data FinalizeHTTPRequest Source #
Finalizes the HTTP request.
Being thrown from an asynchronous variable handler, this exception makes Nginx finalize the current HTTP request with the supplied HTTP status and an optional body. If the body is Nothing then the response will be styled by the Nginx core.
Since: 1.6.3
FinalizeHTTPRequest Int (Maybe String) | Contains HTTP status and body |
Instances
Exception FinalizeHTTPRequest Source # | |
Defined in NgxExport | |
Show FinalizeHTTPRequest Source # | |
Defined in NgxExport showsPrec :: Int -> FinalizeHTTPRequest -> ShowS # show :: FinalizeHTTPRequest -> String # showList :: [FinalizeHTTPRequest] -> ShowS # | |
Eq FinalizeHTTPRequest Source # | |
Defined in NgxExport (==) :: FinalizeHTTPRequest -> FinalizeHTTPRequest -> Bool # (/=) :: FinalizeHTTPRequest -> FinalizeHTTPRequest -> Bool # |
Re-exported data constructors from Foreign.C
Re-exports are needed by exporters for marshalling in foreign calls.
Haskell type representing the C int
type.
(The concrete types of Foreign.C.Types are platform-specific.)
Instances
Storable CInt | |
Defined in Foreign.C.Types | |
Bits CInt | |
Defined in Foreign.C.Types (.&.) :: CInt -> CInt -> CInt # (.|.) :: CInt -> CInt -> CInt # complement :: CInt -> CInt # shift :: CInt -> Int -> CInt # rotate :: CInt -> Int -> CInt # setBit :: CInt -> Int -> CInt # clearBit :: CInt -> Int -> CInt # complementBit :: CInt -> Int -> CInt # testBit :: CInt -> Int -> Bool # bitSizeMaybe :: CInt -> Maybe Int # shiftL :: CInt -> Int -> CInt # unsafeShiftL :: CInt -> Int -> CInt # shiftR :: CInt -> Int -> CInt # unsafeShiftR :: CInt -> Int -> CInt # rotateL :: CInt -> Int -> CInt # | |
FiniteBits CInt | |
Defined in Foreign.C.Types | |
Bounded CInt | |
Enum CInt | |
Ix CInt | |
Num CInt | |
Read CInt | |
Integral CInt | |
Real CInt | |
Defined in Foreign.C.Types toRational :: CInt -> Rational # | |
Show CInt | |
NFData CInt | Since: deepseq-1.4.0.0 |
Defined in Control.DeepSeq | |
Eq CInt | |
Ord CInt | |
Haskell type representing the C unsigned int
type.
(The concrete types of Foreign.C.Types are platform-specific.)
Instances
Storable CUInt | |
Bits CUInt | |
Defined in Foreign.C.Types (.&.) :: CUInt -> CUInt -> CUInt # (.|.) :: CUInt -> CUInt -> CUInt # xor :: CUInt -> CUInt -> CUInt # complement :: CUInt -> CUInt # shift :: CUInt -> Int -> CUInt # rotate :: CUInt -> Int -> CUInt # setBit :: CUInt -> Int -> CUInt # clearBit :: CUInt -> Int -> CUInt # complementBit :: CUInt -> Int -> CUInt # testBit :: CUInt -> Int -> Bool # bitSizeMaybe :: CUInt -> Maybe Int # shiftL :: CUInt -> Int -> CUInt # unsafeShiftL :: CUInt -> Int -> CUInt # shiftR :: CUInt -> Int -> CUInt # unsafeShiftR :: CUInt -> Int -> CUInt # rotateL :: CUInt -> Int -> CUInt # | |
FiniteBits CUInt | |
Defined in Foreign.C.Types finiteBitSize :: CUInt -> Int # countLeadingZeros :: CUInt -> Int # countTrailingZeros :: CUInt -> Int # | |
Bounded CUInt | |
Enum CUInt | |
Ix CUInt | |
Num CUInt | |
Read CUInt | |
Integral CUInt | |
Real CUInt | |
Defined in Foreign.C.Types toRational :: CUInt -> Rational # | |
Show CUInt | |
NFData CUInt | Since: deepseq-1.4.0.0 |
Defined in Control.DeepSeq | |
Eq CUInt | |
Ord CUInt | |