Pedestalを利用したClojureによるマイクロサービスの為のREST APIの実装

Pedestalのコンセプト

Microservices with Clojureより。前回はマイクロサービスのためのRESTのAPI概要について述べた。今回は、Pedestalを利用したClojureによる具体的なマイクロサービスの為のREST APIの実装について述べる。

PedestalはAPIファーストのClojureフレームワークで、動的な性質を持つ信頼性の高い並行サービスを構築するためのライブラリ群を提供するデータ駆動型の拡張可能なフレームワークであり、コンポーネント間の結合を減らすためにプロトコルを使って実装されている。関数よりもデータを、マクロよりも関数を優先する。データ駆動型のルートやハンドラを作成することができ、入力されたリクエストに応じて実行時に異なる動作をさせることができる。これにより、マイクロサービスベースのアプリケーションに適した、柔軟で動的なサービスを作成することができる。また、SSE（server-sent events）やWebSocketを利用したスケーラブルな非同期サービスの構築もサポートする。

Pedestalのアーキテクチャは、InterceptorsとContext Mapという2つのメインコンセプトと、Chain ProviderとNetwork Connectorsという2つのサブコンセプトで構成されている。PedestalフレームワークのコアロジックはすべてInterceptorとして実装されているが、HTTPコネクションハンドラは分離され、実行を開始するための初期コンテキストマップとInterceptorのキューをセットアップするChain Providerのインターフェースが作成されている。Pedestal にはサーブレットチェーンプロバイダが含まれており、サーブレットを扱う全ての HTTP サーバで動作する。また、インターセプターがコントラクトに従って必要とするキーをコンテキストマップにセットアップする。PedestalアプリケーションはHTTPだけに限定されるものではない。他のアプリケーションのプロトコルをサポートするために、カスタムチェーンプロバイダを書くこともできる。また、ターゲットチェーンプロバイダとネットワークコネクタの組み合わせにより、信頼性の高いUDPのような異なるトランスポートプロトコルで動作させることも可能となる。

Pedestalは当初、PedestalアプリケーションとPedestalサーバーという2つの独立した部分を持っていた。Pedestalアプリケーションは、ClojureScriptベースのフロントエンドフレームワークであったが、現在は廃止されている。現在では、信頼性の高いサービスとAPIを構築するために、Pedestalサーバにのみ焦点が当てられている。

もしインターセプターによって :bindings map が変更され、出力のコンテキストマップに返された場合、Pedestal はチェーン内の次のインターセプターを実行する前に、新しいバインディングをスレッドローカルバインディングとしてインストールする。io.pedestal.interceptor.chain/queue コンテキストキーには、まだ実行されていないすべての interceptor が含まれている。キューの最初のインターセプターは、:enter 関数を呼び出すことで次に実行されるとみなされるインターセプターとなる。このキーはデバッグのためにのみ使用しなければならない。キューや実行の流れを変更するためには、このキーの値を変更する代わりに、インターセプターチェーンのenqueue、terminate、terminate-when を呼ばなければならない。io.pedestal.interceptor.chain/terminators のキーで指定された終了述語は :enter関数が呼ばれるたびに、真の述語があるかどうかを調べる。有効な述語が見つかった場合、Pedestalは残りのすべてのインターセプターの:enter関数をスキップして、スタック内のインターセプターの:leave関数を実行し、実行フローを終了させ始める。

io.pedestal.interceptor.chain/stack コンテキストキーには、 :enter 関数がすでに呼び出されているが :leave 関数が保留されている Interceptor が含まれる。スタックの一番上にあるインターセプターが最初に実行され、:leave 関数が :enter 関数の呼び出しと逆の順序で呼び出されるようにする。

インターセプターチェーンによって追加されたキーに加えて、コンテキストマップは他のインターセプターによって追加されたキーも含むことができる。例えば、Pedestal が標準で提供するサーブレットインターセプター は、 :servlet-request, :servlet- response, :servlet-config, :servlet など、サーブレット固有のキーをコンテキストマップに追加している。HTTPサーバーを扱う場合、Context Mapには:requestと:responseというキーもあり、それぞれrequest と responseというマップが割り当てられている。

Pedestalは、HTTPサービスだけにとどまらず、様々なサービスを拡張することができる。Kafkaのようなシステムにサービスを拡張したり、SCTP、Reliable UDP、UDTなどの異なるプロトコルを使用することもできる。pedestal.service Pedestalモジュールは、HTTPに特化したインターセプターの集合体となる。

Pedestalサービスを実装する

Pedestalは、Pedestalサービスに必要な依存関係とディレクトリレイアウトを持つ新しいプロジェクトを作成するために、pedestal-serviceという名前のleiningenテンプレートを提供している。このテンプレートを使って新しいプロジェクトを作成するには、以下のようにテンプレート名とプロジェクト名を指定して、leinコマンドを使用する。

lein new pedestal-service pedestal-play

leinコマンドは、指定されたプロジェクト名で新しいディレクトリを作成し、project.cljファイルに必要なすべての依存関係を追加する。作成されたプロジェクトのディレクトリツリーは、以下のようになる。

> tree pedestal-play
pedestal-play
├── Capstanfile
├── config
│ └── logback.xml ├── Dockerfile
├── project.clj
├── README.md
├── src
│　　|_____pedestal_play
│          |_______ server.clj
│          |_______ service.clj
└── test
　　　└── pedestal_play 
　　　　　　　　└── service_test.clj

プロジェクトを実行するには、lein runコマンドを使用するだけで、テンプレートで定義されたサンプルサービスがコンパイルされ、8080番ポートで開始される。サービスをテストするには、ブラウザでhttp://localhost:8080 と http://localhost:8080/about を開き、レスポンスを観察できる。最初のURLではHello World! が、2番目のURLではClojure 1.10.0 – served from /aboutがレスポンスとして返される。

また、両エンドポイントは、以下のようにcURLからアクセスすることもできる。

>curl -v http://localhost:8080

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET / HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.79.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Tue, 30 Aug 2022 00:59:05 GMT
< Strict-Transport-Security: max-age=31536000; includeSubdomains
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< X-Download-Options: noopen
< X-Permitted-Cross-Domain-Policies: none
< Content-Security-Policy: object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;
< Content-Type: text/html;charset=utf-8
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
Hello World!%

(ns pedestal-play.service
  (:require [io.pedestal.http :as http]
            [io.pedestal.http.route :as route]
            [io.pedestal.http.body-params :as body-params]
            [ring.util.response :as ring-resp]))

(defn about-page
  [request]
  (ring-resp/response (format "Clojure %s - served from %s"
                              (clojure-version)
                              (route/url-for ::about-page))))

(defn home-page
  [request]
  (ring-resp/response "Hello World!"))

(def routes #{["/" :get (conj common-interceptors `home-page)]
              ["/about" :get (conj common-interceptors `about-page)]})

(def routes #{{:app-name "Pedestal Play" :host "localhost" :port 8080
   :scheme :http}
                 ["/" :get (conj common-interceptors `home-page)]
                 ["/about" :get (conj common-interceptors `about-page)]})

routersを宣言する

routersは、定義されたRoutesに基づいてリクエストを分析するために、インターセプターとしてチェーンに追加される関数となる。Pedestalは、ルータを作成する際に、ルータをサービスマップで指定された :io.pedestal.http/routesと :io.pedestal.http/routerのキーの値に基づいて作成する。サービスマップには、ルーター、ルート、チェーンプロバイダのプロパティなど、Pedestalがサービスを作成するためのすべての詳細が含まれている。これは、Pedestalサービスのビルダーとして機能する。
Pedestalには3つの組み込みroutersがあり、:map-tree, :prefix-tree, :prefix-treeを使用して指定できる。 :map-treeはデフォルトのルーターで、静的なすべてのルートに適用された場合、一定の時間複雑性を持つ。パスパラメーターやワイルドカードを持つルートがある場合は、prefix-tree にフォールバックする。
io.pedestal.http/router の値を関数として指定すると、その関数を使用してルータを構築する。この関数は、1つの引数、すなわち冗長形式のルートコレクションを取り、ルータプロトコルを満たすルータを返さなければならない。

リクエストパラメーターにアクセスする

Servlet Chain Providerは、リクエストマップをコンテキストマップにアタッチする。リクエストマップには、APIのクライアントが指定したすべてのフォーム、クエリ、URL パラメータが含まれる。これらのパラメータは、キーと値のペアのマップとして定義され、各キーはクライアントによって指定されたパラメータを表す。すべてのパラメータはオプションであり、クライアントがリクエストで指定した場合のみ存在する。以下は、リクエスト・マップに含まれる可能性のあるキーのリストとなる。

パラメータとは別に、リクエストマップには常に存在するこれらのキーもあり、チェーン内のインターセプターが使用することができる。

リクエスト マップを確認するには、次のコードに示すように、新しい debug-page ハンドラを pedestal-play プロジェクトに追加して、ルート /debug にマッピングする。この ハンドラ debug-page は、関心のあるパラメータ キーのみを含むリクエスト マップをレスポンスで返す。また、このコードはCheshireライブラリを使用して、JSON 文字列に変換している。

(defn debug-page
     [request]
     (ring-resp/response
      (cheshire.core/generate-string
       (select-keys request
          [:params :path-params :query-params :form-params]))))
   ;; Common Interceptors used for all routes
   (def common-interceptors [(body-params/body-params) http/html-body])
   (def routes #{{:app-name "Pedestal Play" :host "localhost" :port 8080
   :scheme :http}
                 ["/" :get (conj common-interceptors `home-page)]
                 ["/about" :get (conj common-interceptors `about-page)]
                 ["/debug/:id" :post (conj common-interceptors `debug-page)]})

次の例に示すように、/debug ルートへの cURL リクエストは、path、query、formのパラメータを検査することができるリクエストマップ全体を提供する。

>curl -XPOST -d "formparam=1" "http://localhost:8080/debug/1?qparam=1"
{
  "params": {
    "qparam": "1",
    "formparam": "1"
  },
  "path-params": {
  "id": "1" },
  "query-params": {
    "qparam": "1"
  },
  "form-params": {
    "formparam": "1"
  }
}

interceptorsを作る

Pedestalのインターセプターは :name, :enter, :leave, :error をキーとするマップとして定義することができる。例えば、msg-play というインターセプターを定義して、 pedestal-play プロジェクトの /hello ルートに対して、クエリパラメータ名を大文字し、:leave 関数を用いて終了時に挨拶を追加するように変更することができる。

;; Handler for /hello route
   (defn hello-page
     [request]
     (ring-resp/response
      (let [resp (clojure.string/trim (get-in request [:query-params :name]))]
        (if (empty? resp) "Hello World!" (str "Hello " resp "!")))))
   (def msg-play
     {:name ::msg-play
      :enter
      (fn [context]
         (update-in context [:request :query-params :name]
   clojure.string/upper-case))
:leave
  (fn [context] (update-in context [:response :body]
                               #(str % "Good to see you!")))})
   ;; Common Interceptors used for all routes
   (def common-interceptors [(body-params/body-params) http/html-body])
   (def routes #{{:app-name "Pedestal Play" :host "localhost" :port 8080
   :scheme :http}
                 ["/" :get (conj common-interceptors `home-page)]
                 ["/about" :get (conj common-interceptors `about-page)]
                 ["/debug/:id" :post (conj common-interceptors `debug-page)]
                 ["/hello" :get
                  (conj common-interceptors `msg-play `hello-page)]}) 

cURL から /hello ルートへ name クエリパラメータでリクエストすると、 msg- の :enter と :leave イベントが発生し、期待通りの結果が得られる。

>curl "http://localhost:8080/hello?name=clojure"
 Hello CLOJURE!Good to see you!

クエリパラメータが指定されていない場合は、hello-page インターセプタの実装に従った Hello World グリーティングを返すものとなる。

>curl "http://localhost:8080/hello?name="
 Hello World!Good to see you!

次回は次世帯DB Datomicを利用したマイクロサービスの為のデータベース構築について述べる。