RPC на основе WAI

"Алексей Пирогов" 2015 sep 01 tags ["WAI"]

original

Введение

Сейчас web-разработка на Haskell достаточно проста, даже для новичка. Этому способствует наличие таких пакетов, как Yesod и Snap. Но не всегда их мощь и полнота охвата необходимы. Порой от “сервера” требуется столь мало, что не хочется иметь в зависимостях подобных “монстров”, особенно в тех случаях, когда задача достаточно легко решаема и более простыми средствами.

Пусть примером послужит такая задача: требуется реализовать сервис, позволяющий вызывать на сервере некие функции и получать результат вызова, или, говоря общепринятым языком, выполнять RPC.

Такую задачу можно решить, используя Spock, scotty или, скажем, servant, но “мы пойдем другим путем”©!

Большинство библиотек для web-разработки внутри использует так называемый Web Application Interface (WAI) - обобщенный протокол общения web-сервера и web-приложения. Приложения, реализующие этот протокол, называют WAI-приложениями и запускают с помощью сервера wai-приложений - warp.

Реализуем же и мы простой сервис на чистом WAI!

WAI-сервис

Задача

Реализовать сервис вызова функций типа String -> String. Для примера реализуем функции reverse, upper и lower.

API будет следующим:

GET на / возвращает список имен доступных функций (по одному на строку),
GET на /<function_name> возвращает описание функции,
GET на /<function_name>?<argument> возвращает результат вызова функции.

“Hello, World!”

Для начала создадим проект и реализуем сервер-заглушку, отвечающий известной строкой на любой запрос. Обратите внимание: исходники проекта доступны на github.

Создаем проект:

  $ stack new wai-rpc simple --resolver lts-3.2

ВНИМАНИЕ: предполагается, что у вас установлена утилита stack, а ключ --resolver lts-3.2 означает, что будет использоваться снимок версии 3.2 - именно этот снимок был актуален на момент написания статьи. (подробнее о снимках можно почитать в документации к stack).

После создания проекта добавляем зависимости http-types, wai и warp в .cabal-файл:

  -- ...часть файла опущена...
  executable wai-rpc
    hs-source-dirs:      src
    main-is:             Main.hs
    default-language:    Haskell2010
    build-depends:       base >= 4.7 && < 5,
                         http-types, wai, warp -- <-- добавлено

Затем содержимое файла src/Main.hs заменяем на:

  {-# LANGUAGE OverloadedStrings #-}
  module Main where

  import Network.Wai
  import Network.HTTP.Types (status200, hContentType)
  import Network.Wai.Handler.Warp (run)

  application :: Application
  application _ respond = respond $
    responseLBS status200
                [(hContentType, "text/plain")]
                "Hello World"

  main :: IO ()
  main = do
    putStrLn "Serving..."
    run 8000 application

К слову, этот код практически слово-в-слово повторяет helloworld от авторов библиотеки WAI ;)

Осталось собрать проект:

  $ stack build

И запустить:

  $ stack exec wai-rpc
  Serving (hit Ctrl+C to stop)...

Если при запущенном сервере открыть в браузере url http://localhost:8000, то в окне отобразится ожидаемое приветствие. Сервер работает!

Теперь стоит разобрать, из чего же состоит наш сервер.

main содержит строку

run 8000 application

Это запуск сервера warp на порту 8000 с единственным WAI-приложением - application.

Приложение application имеет тип Application, который является синонимом для

  type Application = Request
                     -> (Response -> IO ResponseReceived)
                     -> IO ResponseReceived

Здесь первый аргумент, это тип Request, описывающий запрос, а второй, это “ответчик” - функция, призванная возвращать ответ Response в процессе выполнения некой работы (для этого в типе монада IO).

В данном случае приложение сразу же отвечает фиксированным сообщением, поэтому тело приложения - единственный вызов ответчика respond.

Ответ же в данном случае выглядит так:

  responseLBS status200
              -- :: Network.HTTP.Types.Status
              [(hContentType, "text/plain")]
              -- :: [(Network.HTTP.Types.HeaderName
              --     ,ByteString)]
              "Hello World!"
              -- :: Lazy ByteString

Всё достаточно привычно: статус, заголовки и тело.

Вот, собственно и всё! Это уже вполне самостоятельный сервер, можно пускать в production :) И это не шутка - warp испытан и проверен, и, ко всему прочему, весьма быстр и пригоден для “вывешивания наружу” (т.е. не требует заворачивания во всякие Nginx).

Маршрутизация

Сервер работает, настало время решать конкретную задачу. Для начала заведем несколько вспомогательных функций для работы с ответами:

  import Network.Wai (Response)
  import Network.HTTP.Types (Status, notFound404,
                             badRequest400)
  import qualified Data.ByteString.Lazy as LBS

  -- ...

  responseOk, responseNotFound, responseBadRequest
    :: LBS.ByteString -> Response
  responseOk         = responsePlainText status200
  responseNotFound   = responsePlainText notFound404
  responseBadRequest = responsePlainText badRequest400

  responsePlainText :: Status -> LBS.ByteString -> Response
  responsePlainText =
    (`responseLBS` [(hContentType, "text/plain")])

(в зависимости проекта нужно будет добавить bytestring)

Так как мы собираемся обрабатывать только GET-запросы, добавим отсечку по типу запроса с соответствующим сообщением об ошибке:

  import Network.Wai (requestMethod)
  import Network.HTTP.Types (methodGet)

  application req respond = respond $
    if requestMethod req /= methodGet
    then responseBadRequest "Only GET method is allowed!"
    else -- далее всё как раньше с учетом вспом. функций
      responseOk "Hello World"

GET-запросы мы уже фильтруем, теперь на запрос к корневому url нужно возвращать список функций. Значит нужна библиотека функций:

  import Data.Map.Strict (Map, fromList, lookup, keys)
  import qualified Data.ByteString.Char8 as BS
  import Prelude hiding (lookup)

  -- ...

  type FunctionName        = BS.ByteString
  type FunctionDescription = BS.ByteString
  type FunctionArg         = BS.ByteString
  type FunctionResult      = BS.ByteString
  type FunctionSpec        = (FunctionDescription
                             ,(FunctionArg -> FunctionResult))

  library :: Map FunctionName FunctionSpec
  library = fromList []

  getFunctionSpec :: FunctionName -> Maybe FunctionSpec
  getFunctionSpec = (`lookup` library)

  listOfFunctions :: [FunctionName]
  listOfFunctions = keys library

  describe :: FunctionSpec -> FunctionDescription
  describe = fst

  call :: FunctionSpec -> FunctionArg -> FunctionResult
  call = snd

(в зависимости проекта нужно будет добавить containers)

Самих функций пока нет, но библиотека есть, как есть и функции для работы с ней. Можно уже выводить список функций, но перед этим нужно понять, что запрос производится на “корневой” url и не содержит параметров. Добавим ветвления в наше приложение, заодно переписав if-ветки в виде охранных выражений:

  import Network.Wai (rawPathInfo, rawQueryString)

  -- ...

  application req respond
    | requestMethod req /= methodGet =
      respond
      $ responseBadRequest "Only GET method is allowed!"

    | path == "" =
      respond
      $ if query /= ""
        then responseBadRequest "No query parameters needed!"
        else responseOk renderedListOfFunctions

    | otherwise =
      respond
      $ responseOk "Hello World"

    where
      query = rawQueryString req
      path  = BS.tail $ rawPathInfo req -- без ведущего '/'

      renderedListOfFunctions =
        LBS.intercalate "\n"
        $ "Available functions:"
          : map LBS.fromStrict listOfFunctions

Теперь у нашего сервера есть маршрутизация, пусть и в зачаточном виде :)

Проверим работу того, что уже наработано, с помощью curl (предполагается, что сервер запущен в другом окне терминала):

  $ curl http://localhost:8000
  Available functions:

  $ curl http://localhost:8000?asdf
  No query parameters needed!

Получение описание и вызов функций

Теперь корневой url обрабатывается. Настало время поиска функции в библиотеке:

  application req respond
    -- тут существующая маршрутизация
    | otherwise =
      respond
      $ maybe
      (responseNotFound "Unknown function!")
      (\spec -> responseOk
                $ LBS.fromStrict
                $ if query == ""
                  then describe spec
                  else call spec query)
      $ getFunctionSpec path

Функций пока нет, но поиск уже работает. Проверим:

  $ curl http://localhost:8000/func
  Unknown function!

Добавим же наконец пару функций в библиотеку:

  import Data.Char (toUpper)

  -- ...

  library :: Map FunctionName FunctionSpec
  library =
    fromList [("reverse", ("returns string with characters in reverset order",
                           BS.reverse ))
             ,("upper",   ("returns string with each character in upper case",
                           BS.map toUpper ))]

И, разумеется, проверим:

  $ curl http://localhost:8000
  Available functions:
  reverse
  upper

  $ curl http://localhost:8000/reverse
  returns string with characters in reverset order

  $ curl http://localhost:8000/reverse?Hello+World
  dlroW olleH

Готово! Есть функции, и их можно вызывать удалённо!

Финальные штрихи

Сервер у нас есть, но неплохо было бы видеть какие запросы он получает и что на них отвечает, т.е. нам нужно логирование. Существует готовый пакет wai-logger, однако для практики мы напишем свою реализацию логирования - тоже простейшую.

Когда при работе с WAI-приложениями возникает необходимость сделать что-то с запросами и/или ответами на них, на сцену выходит тип Middleware:

  Middleware :: Application -> Application

Middleware - это преобразователь приложений, настоящая функция высшего порядка! Как же такие преобразователи пишутся? Довольно просто:

  import Network.Wai (Middleware, responseStatus)
  import Network.HTTP.Types (statusCode)

  -- ...

  withLogging :: Middleware
  withLogging app req respond =
    app req $ \response -> do
      putStrLn $ statusOf response ++ ": " ++ query
      respond response
    where
      query = BS.unpack
            $ BS.concat [ rawPathInfo    req
                        , rawQueryString req ]
      statusOf = show . statusCode . responseStatus

   main = do
     putStrLn ...
     run 8000 $ withLogging application

Ничего сверх-естественного, оборачивание вызова функции, как оно есть.

Выглядит вывод logger’а примерно так:

  $ stack exec wai-rpc
  Serving (hit Ctrl+C to stop)...
  200: /reverse?Hello%20World
  200: /
  404: /asdf
  400: /?asdf
  ...

Подобным образом можно осуществлять маршрутизацию, проверку на наличие, или отсутствие cookies, оптимизацию(сжатие) ответов и кэширование запросов. Такой подход, на мой взгляд, очень композируем да и просто и элегантен!

Заключение

Даже такой простой пример позволяет понять, что разработка сервисов на “голом” WAI не только довольно проста, но и вполне удобна и приятна :)