This module implements a number of exporters for simple services. Here simplicity means avoiding boilerplate code regarding to efficient reading of typed configurations and timed restarts of services.

All simple services are classified as untyped or typed. The untyped services have type

ByteString -> Bool -> IO ByteString

which corresponds to the type of usual services from module NgxExport. The typed services are backed by functions from module NgxExport.Tools.Read and may have two different types:

Read a => a -> Bool -> IO ByteString

FromJSON a => a -> Bool -> IO ByteString

The choice of a certain type of a typed service depends on the format in which the typed data will be passed from the Nginx configuration.

Below is a simple example.

File test_tools.hs

{-# LANGUAGE TemplateHaskell, DeriveGeneric, RecordWildCards #-}

module TestTools where

import           NgxExport
import           NgxExport.Tools

import           Data.ByteString (ByteString)
import qualified Data.ByteString.Lazy as L
import qualified Data.ByteString.Lazy.Char8 as C8L
import           Data.Aeson
import           Data.IORef
import           Control.Monad
import           GHC.Generics

test :: ByteString -> Bool -> IO L.ByteString
test = const . return . L.fromStrict
ngxExportSimpleService 'test $
    PersistentService $ Just $ Sec 10

showAsLazyByteString :: Show a => a -> L.ByteString
showAsLazyByteString = C8L.pack . show

testRead :: Show a => a -> IO L.ByteString
testRead = return . showAsLazyByteString

testReadInt :: Int -> Bool -> IO L.ByteString
testReadInt = const . testRead
ngxExportSimpleServiceTyped 'testReadInt ''Int $
    PersistentService $ Just $ Sec 10

newtype Conf = Conf Int deriving (Read, Show)

testReadConf :: Conf -> Bool -> IO L.ByteString
testReadConf = const . testRead
ngxExportSimpleServiceTyped 'testReadConf ''Conf $
    PersistentService $ Just $ Sec 10

testConfStorage :: ByteString -> IO L.ByteString
testConfStorage = const $
    showAsLazyByteString <$> readIORef storage_Conf_testReadConf
ngxExportIOYY 'testConfStorage

data ConfWithDelay = ConfWithDelay { delay :: TimeInterval
                                   , value :: Int
                                   } deriving (Read, Show)

testReadConfWithDelay :: ConfWithDelay -> Bool -> IO L.ByteString
testReadConfWithDelay c@ConfWithDelay {..} fstRun = do
    unless fstRun $ threadDelaySec $ toSec delay
    testRead c
ngxExportSimpleServiceTyped 'testReadConfWithDelay ''ConfWithDelay $
    PersistentService Nothing

data ConfJSON = ConfJSONCon1 Int
              | ConfJSONCon2 deriving (Generic, Show)
instance FromJSON ConfJSON

testReadConfJSON :: ConfJSON -> Bool -> IO L.ByteString
testReadConfJSON = ignitionService testRead
ngxExportSimpleServiceTypedAsJSON 'testReadConfJSON ''ConfJSON
    SingleShotService

Here five simple services of various types are defined: test, testReadInt, testReadConf, testReadConfWithDelay, and testReadConfJSON. Typed services hold IORef storages to save their configurations for faster access in future iterations. The name of a storage consists of the name of its type and the name of the service connected by an underscore and prefixed as a whole word with storage_.

As soon as all the services in the example merely echo their configurations into their service variables, they must sleep for a while between iterations. Sleeps are managed by strategies defined in type ServiceMode. There are basically three sleeping strategies:

• Periodical sleeps (for example, PersistentService $ Just $ Sec 10)
• No sleeps between iterations (PersistentService Nothing)
• Single-shot services (SingleShotService)

In this toy example the most efficient sleeping strategy is a single-shot service because data is not altered during runtime. A single-shot service runs exactly two times during the lifetime of a worker process: the first run (when the second argument of the service, i.e. the first-run flag, is True) is immediately followed by the second run (when the first-run flag is False). On the second run the service handler is used as an exception handler when the service is shutting down after the WorkerProcessIsExiting exception has been thrown. Accordingly, a single-shot handler can be used for allocation of some global resources (when the first-run flag is True), and cleaning them up (when the first-run flag is False).

Notice that service testReadConfWithDelay manages time delays on its own, therefore it uses no-sleeps strategy PersistentService Nothing.

File nginx.conf

user                    nobody;
worker_processes        2;

events {
    worker_connections  1024;
}

http {
    default_type        application/octet-stream;
    sendfile            on;

    haskell load /var/lib/nginx/test_tools.so;

    haskell_run_service simpleService_test
            $hs_test
            test;

    haskell_run_service simpleService_testReadInt
            $hs_testReadInt
            5000000;

    haskell_run_service simpleService_testReadConf
            $hs_testReadConf
            'Conf 20';

    haskell_run_service simpleService_testReadConfWithDelay
            $hs_testReadConfWithDelay
            'ConfWithDelay { delay = Sec 10, value = 12 }';

    haskell_run_service simpleService_testReadConfJSON
            $hs_testReadConfJSON
            '{"tag":"ConfJSONCon1", "contents":56}';

    server {
        listen       8010;
        server_name  main;
        error_log    /tmp/nginx-test-haskell-error.log;
        access_log   /tmp/nginx-test-haskell-access.log;

        location / {
            haskell_run testConfStorage $hs_testConfStorage '';

            echo "Service variables:";
            echo "  hs_test: $hs_test";
            echo "  hs_testReadInt: $hs_testReadInt";
            echo "  hs_testReadConf: $hs_testReadConf";
            echo "  hs_testReadConfWithDelay: $hs_testReadConfWithDelay";
            echo "  hs_testReadConfJSON: $hs_testReadConfJSON";
            echo "Storages of service variables:";
            echo "  hs_testConfStorage: $hs_testConfStorage";
        }
    }
}

Notice that Haskel handlers defined in test_tools.hs are referred from the Nginx configuration file with prefix simpleService_.

A simple test

$ curl 'http://localhost:8010/'
Service variables:
  hs_test: test
  hs_testReadInt: 5000000
  hs_testReadConf: Conf 20
  hs_testReadConfWithDelay: ConfWithDelay {delay = Sec 10, value = 12}
  hs_testReadConfJSON: ConfJSONCon1 56
Storages of service variables:
  hs_testConfStorage: Just (Conf 20)

Storages of typed simple services can be preloaded synchronously with ngxExportInitHook. This is useful if a storage gets accessed immediately after the start of processing client requests in a request handler which expects that the storage has already been initialized (for example, a request handler may unpack the storage with fromJust without checking errors).

File test_tools.hs: preload storage_Int_testReadInt

import           System.Environment

-- ...

initTestReadInt :: IO ()
initTestReadInt = do
    _ : v : _ <- dropWhile (/= "--testReadInt") <$> getArgs
    let i = read v
    i `seq` writeIORef storage_Int_testReadInt (Just i)
ngxExportInitHook 'initTestReadInt

Note that the preloaded value gets evaluated inside the hook to spot any parse errors inplace before the start of processing client requests.

File nginx.conf: read data for storage_Int_testReadInt

    haskell program_options --testReadInt 800;

    # ...

    haskell_run_service simpleService_testReadInt
            $hs_testReadInt
            -;

The preloaded value gets passed in directive haskell program_options. The value in the service declaration can be replaced by any lexeme as it won't be parsed. In this example, it was replaced by a dash.

Re-exports are needed by exporters for marshalling in foreign calls.