リクエスト書き換えプラグイン¶

Mayhem はプラグインによるリクエスト書き換えをサポートしています。プラグインは、protobuf インターフェイスを実装し、gRPC を通じて公開されるスタンドアロンプログラムです。

インターフェイスの詳細は下記のとおりです。その前に、以下を説明します。

この機能が必要な場合¶

Mayhem はできるだけ多くのユースケースにそのまま利用できるよう設計されており、これからも機能の追加が続けられます。リクエスト書き換えプラグインは、API に現時点の Mayhem がそのままでは対応できない要件がある場合のいわば緊急避難の手段として用意されています。

以下は、機能を開発する際に想定されたケースの例です。

ジャストインタイム認証¶

テストジョブの最中に認証が変化する状況では、現時点で Mayhem for API には解決策がありません。

リクエスト書き換えプラグインは、API が要求する任意のタイミングで適切な認証情報を注入できます。

リクエストダイジェスト/署名¶

API が何らかのダイジェストまたは署名を認証手段として使用している場合、Mayhem は有効なリクエストを生成できません。

リクエスト書き換えプラグインは、リクエストごとにチェックサムまたは署名を計算し、注入できます。

その他¶

リクエストプラグインのインターフェイスは非常に自由度が高く、リクエストのどのような部分でも書き換えできます。

何らかの理由でリクエスト書き換えプラグインの利用を検討している場合、お問い合わせください。この機能はまだ導入されたばかりであり、ユーザーがどのように機能を利用されているか、またどのような改善が可能かを知りたいと考えています。

インターフェイス¶

呼び出し¶

API テストのランにリクエスト書き換えプラグインを追加するには、 mapi run に --rewrite-plugin <path-to-plugin-executable> 引数を指定します。

実行可能 gRPC サーバー¶

mapi はコマンドライン引数なしで実行ファイルを実行し、実行ファイルが以下の特徴を持つ長期間実行されるプロセスであることを期待します。 * localhost のポートで gRPC トラフィックを待機する * 標準出力の先頭行としてポート番号の後に改行を出力する

この他の処理に制限はありません。プラグインからの追加の標準出力/標準エラー出力は、mapi デバッグログにフォワードされます。

テストランが終了すると、mapi はプラグインプロセスを終了しようとします。

Protobuf¶

リクエスト書き換えプラグインは、次の protobuf インターフェイスを実装します。

syntax = "proto3";

package mapi.rewrite;

service RewritePlugin {
   rpc Rewrite(Request) returns (Request);
}

message Request {
   message Header {
      bytes name = 1;
      bytes value = 2;
   }
   string url = 1;
   repeated Header headers = 2;
   bytes body = 3;
   string http_method = 4;
}

サンプル¶

次に挙げるのは、リクエスト書き換えプラグインのサンプルです。このプラグインは、まったく何も処理せず、元のリクエストをそのまま返しているだけです。

まず、.proto からすべての gRPC および protobuf のボイラープレートを生成します。

$ pip install grpcio-tools
$ python -m grpc_tools.protoc --python_out=. --grpc_python_out=. -I. request-rewrite-plugin.proto

次に、RewritePluginServicer を実装する Python プログラムを作成し、 gRPC サーバーを立ち上げ、mapi に待機するポートを指示します。

#!/usr/bin/env python

import sys
from concurrent import futures
import grpc
import request_rewrite_plugin_pb2
import request_rewrite_plugin_pb2_grpc

## implement the RewritePlugin interface
class RewritePluginServicer(request_rewrite_plugin_pb2_grpc.RewritePluginServicer):
    def Rewrite(self, request, context):
        ## well, this isn't very interesting :)
        return request

if __name__ == '__main__':
    ## boot up the gRPC server
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    request_rewrite_plugin_pb2_grpc.add_RewritePluginServicer_to_server(
        RewritePluginServicer(), server)
    server.add_insecure_port('127.0.0.1:50051')
    server.start()

    ## inform mapi of the port we're listening on
    print("50051")
    sys.stdout.flush()

    server.wait_for_termination()

.py ファイルが実行可能であることを確認したら、--rewrite-plugin を使用して mapi に渡します。これで完了です。

その他のサンプル¶

試用可能なその他のサンプルについては GitHub リポジトリを参照してください。

注意事項¶

文字列ではなくバイト¶

Mayhem API testing のリクエストは、常に文字列として表現可能とはかぎりません。注意してください。

変更の可能性¶

この機能は流動的であり、変更される可能性があります。この機能を利用する場合は、改良や変更を検討する際にお知らせできるよう、当社までご連絡ください。

注入されたヘッダーシークレット¶

書き換えプラグインがリクエストに機密情報を含むヘッダーを追加する場合、 --redact-header オプションを使用して、レポートでは追加されたヘッダーの値を抑制するとよいでしょう。詳細については「ヘッダーシークレットの抑制」を参照してください。