Connection Options¶

対象読者: アーキテクト、管理者、アプリケーションおよびスマートコントラクト開発者

コネクションオプションは、コネクションプロファイルと一緒に使われ、ゲートウェイがどのようにネットワークとやりとりするかを正確に制御するのに用います。ゲートウェイを使うことで、アプリケーションは、ネットワークのトポロジではなく、ビジネスロジックに集中することができます。

このトピックでは次の項目について扱います。

なぜコネクションオプションが大切なのか
アプリケーションがコネクションオプションをどのように使うか
各コネクションオプションの意味
それぞれのコネクションオプションをいつ使うべきか

Scenario¶

コネクションオプションは、ゲートウェイの振る舞いのある一面を指定するものです。ゲートウェイは様々な理由から重要ですが、その主な理由は、アプリケーションが、ネットワークの多くのコンポーネントとのやりとりを管理するなかで、ビジネスロジックやスマートコントラクトに集中できるようにしていることです。

profile.scenario 図中のそれぞれの点は、コネクションオプションが振る舞いを制御している部分です。これらのオプションは、本文で全て説明されています

コネクションオプションの一つの例としては、issueアプリケーションで使われるゲートウェイが、papernetネットワークにトランザクションを送信する際にIsabellaのアイデンティティを使うよう指示するものがあるでしょう。あるいは、ゲートウェイが制御を返すときに、MagnetoCorpの3つの全てのノードがトランザクションをコミットしたことを確認するまで待つというものもあるでしょう。コネクションオプションによって、アプリケーションは、ゲートウェイがネットワークとやりとりする際の振る舞いを指定することができます。ゲートウェイがなければ、アプリケーションははるかに多くの処理をする必要があります。ゲートウェイによって、時間を節約できますし、アプリケーションを読みやすくそしてエラーを減らすことができます。

Usage¶

アプリケーションが利用可能なコネクションオプションの全ては、この後すぐに説明しますが、まずはサンプルのMagnetoCorpのissueアプリケーションでどのように指定されているかを見てみましょう。

const userName = 'User1@org1.example.com';
const wallet = new FileSystemWallet('../identity/user/isabella/wallet');

const connectionOptions = {
  identity: userName,
  wallet: wallet,
  eventHandlerOptions: {
    commitTimeout: 100,
    strategy: EventStrategies.MSPID_SCOPE_ANYFORTX
    }
  };

await gateway.connect(connectionProfile, connectionOptions);

identityとwalletオプションが、connectionOptionオブジェクトの単純なプロパティであることがわかるでしょう。これらのプロパティはそれぞれ、コードのその前でセットされているuserNameとwalletの値をもちます。それだけで一つのオブジェクトとなっているeventHandlerOptionsオプションと対比してみてください。これは、commitTimeOut: 100 (単位は秒)とstrategy: EventStrategies.MSPID_SCOPE_ANYFORTXという二つのプロパティをもっています。

connectionOptionsがゲートウェイに対して、connectionProfileに加えて渡されているのがわかります。コネクションプロファイルでネットワークが識別され、オプションによってゲートウェイがそのネットワークとどのようにやりとりしなければならないかを正確に指定しています。それでは、利用可能なオプションを見ていきましょう。

Options¶

下記が、利用可能なオプションとその意味のリストです。

walletは、アプリケーションの代わりにゲートウェイが使用するウォレットを識別するものです。図中の1を参照してください。ここでは、ウォレットはアプリケーションによって指定されますが、実際にアイデンティティを取得するのはゲートウェイです。

ウォレットは必ず指定する必要があります。決めるべき最も重要な点は、ファイルシステムやインメモリやHSMやデータベースといった、使用するウォレットの種類です。

identityは、walletの中からアプリケーションが使うユーザーのアイデンティティです。図中の2aを参照してください。ユーザーのアイデンティティがアプリケーションによって指定され、それはアプリケーションのユーザーであるIsabella(2b)を代表するものです。アイデンティティは、実際にはゲートウェイが取得します。

この例では、Isabellaのアイデンティティは、異なるMSP(2cと2d)によって、彼女がMagnetoCorpの者であり、ある役割を持っていることを識別するのに使われます。この二つの事実は、それに応じてリソースに対する彼女の権限、たとえば台帳を読んだり書いたりすることができるかどうかを決定します。

ユーザーのアイデンティティは必ず指定する必要があります。このアイデンティティは、明らかにHyperledger Fabricが許可型のネットワークであるということの基礎となるものです。アプリケーション、ピア、Orderer含め、全てのアクターはアイデンティティを持ち、それによってリソースに対する制御を決定されます。この考え方について詳しくは、メンバーシップサービスのトピックを参照してください。

clientTlsIdentityは、ウォレットから取得されるアイデンティ(3a)で、ゲートウェイと、ピアとordererといった様々なチャネルコンポーネントとのセキュア通信で使われます(3b)。

このアイデンティティは、ユーザーのアイデンティティとは異なることに注意してください。 clientTlsIdentityはセキュア通信では重要ですが、ユーザーのアイデンティティのように基礎をなすものではありません。それは、そのスコープがセキュアなネットワーク通信に限られているからです。

clientTlsIdentityはオプショナルです。本番環境においてはセットすることをお勧めします。 clientTlsIdentityとidentityには常に異なるものを使用するべきです。これは、これらのアイデンティティが全く異なる意味とライフサイクルをもつからです。例えば、もしclientTlsIdentityが漏洩した場合には、identityもしてしまうことになるでしょう。二つを別々にしておくことによってよりセキュアになります。

eventHandlerOptions.commitTimeoutはオプショナルです。これは、ゲートウェイがアプリケーションに処理を返す前に、トランザクションがいずれかのピア(4a)でコミットされるまで待つ最大時間を秒単位で指定します。通知のために使うピアのセットは、eventHandlerOptions.strategyオプションで決定されます。もし、commitTimeoutが指定されない場合は、ゲートウェイは300秒のタイムアウトを使用します。

eventHandlerOptions.strategyはオプショナルです。これは、ゲートウェイが、トランザクションがコミットされた通知を受け取るのに使うピアのセットを識別します。たとえば、一つのピアから受け取るのか、その組織のすべてのピアから受け取るのか、などです。以下のいずれかの値をとることができます。
- EventStrategies.MSPID_SCOPE_ANYFORTX: その組織のいずれかのピアから受け取ります。この例では、4bを参照してください。MagnetoCorpのPeer 1、Peer 2、Peer 3のどれでもゲートウェイに通知することができます。
- EventStrategies.MSPID_SCOPE_ALLFORTX: これがデフォルトの値です。ユーザーの組織の全てのピアから受け取ります。この例では、4bを参照してください。 MagnetoCorpの全てのピア、すなわちPeer 1、Peer 2、Peer 3が全てゲートウェイに通知を行っていなければなりません。ピアは、知られている・ディスカバリで発見されている、かつ、利用可能なものだけが対象となります。停止していたり、エラーとなったピアは含まれません。
- EventStrategies.NETWORK_SCOPE_ANYFORTX: ネットワークチャネル全体のいずれかのピアから受け取ります。この例では、4bと4cを参照してください。 MagnetoCorpからのPeer 1-3または、DigiBankのPeer 7-9のどれでもゲートウェイに通知することができます。
- EventStrategies.NETWORK_SCOPE_ALLFORTX: ネットワークチャネル全体の全てのピアから受け取ります。この例では、4bと4cを参照してください。 MagnetoCorpとDigiBakの全てのピア、すなわちPeer1-3とPeer7-9がゲートウェイに通知しなければなりません。ピアは、知られている・ディスカバリで発見されている、かつ、利用可能なものだけが対象となります。停止していたり、エラーとなったピアは含まれません。
- <PluginEventHandlerFunction>: ユーザー定義のイベントハンドラの名前です。これによって、ユーザーがイベント処理に自前のロジックを定義することができます。詳しくは、プラグインイベントハンドラの定義の方法やサンプルハンドラを参照してください。
  
  ユーザー定義のイベントハンドラは、非常に独特なイベントハンドラの要件がある場合にのみ必要となります。一般的には、組み込みのイベントストラテジのいずれかで十分でしょう。ユーザー定義のイベントハンドラの例としては、トランザクションがコミットされたことの確認のために、ある組織の過半数のピアを待つといったものがあるでしょう。
  
  もし、ユーザー定義のイベントハンドラを指定しても、アプリケーションロジックには影響しません。この二つは切り離されたものです。ハンドラは処理の間にSDKによって呼ばれ、SDKはハンドラの結果によってどのピアをイベント通知に使うかを選びます。アプリケーションは、SDKがその処理を終えてから処理を受け取ります。
  
  もし、ユーザー定義のイベントハンドラが指定されなかった場合には、EventStrategiesのデフォルト値が使われます。

discovery.enabledはオプショナルで、trueかfalseのいずれかの値をとります。デフォルトは、trueです。これによって、ゲートウェイがサービスディスカバリを使用して、コネクションプロファイルで指定されたネットワークトポロジを補うかどうかを決めます。図中の6を参照してください。ピアからのゴシップ情報をゲートウェイが使っています。

この値は、INITIALIZE-WITH-DISCOVERY環境変数によって上書きされ、trueかfalseを設定することができます。

discovery.asLocalhostはオプショナルで、trueかfalseのいずれかの値をとります。デフォルトは、trueです。これによって、サービスディスカバリで得られたIPアドレスを、Dockerのネットワークからlocalhostに変換するかどうかを決定します。

開発者は、ピア・orderer・CAといったネットワークコンポーネントとしてDockerコンテナを使うアプリケーションを書き、ただし、アプリケーション自身はコンテナで動かさないことが多いでしょう。これが、trueがデフォルトである理由です。本番環境においては、アプリケーションはネットワークコンポーネントと同様にDockerコンテナで動作することが多いため、アドレス変換は必要ありません。この場合、アプリケーションは、明示的にfalseを指定するか、環境変数による上書きを使用しなければなりません。

この値は、DISCOVERY-AS-LOCALHOST環境変数によって上書きされ、trueかfalseを設定することができます。

Considerations¶

コネクションオプションをどのように選ぶかを決める際には、以下の考慮すべき事項のリストが役に立つでしょう。

eventHandlerOptions.commitTimeoutとeventHandlerOptions.strategyは、組み合わせで意味を持ちます。たとえば、commitTimeout: 100とstrategy: EventStrategies.MSPID_SCOPE_ANYFORTXは、ゲートウェイがいずれかのピアがトランザクションがコミットされたことを最大で100秒まで待つ、ということを意味します。対照的に、strategy: EventStrategies.NETWORK_SCOPE_ALLFORTXは、ゲートウェイは全ての組織の全てのピアを100秒間まで待つということを意味します。

デフォルトであるeventHandlerOptions.strategy: EventStrategies.MSPID_SCOPE_ALLFORTXは、アプリケーションの組織の全てのピアがトランザクションをコミットするまで待ちます。これは、アプリケーションが、自分の組織のピアがすべて最新の台帳のコピーを持つことを確認でき、同時実行による問題を最小化することができるので、良いデフォルト値です。

しかし、組織内のピア数が増えていくと、全てのピアを待つことは多少不要になってきます。この場合、プラグ可能なイベントハンドラによって、より効率的なストラテジを提供することができます。たとえば、合意形成によって全ての台帳が同期されるという想定に基づいて、トランザクションを送信するのと通知を受け取るのに、同じピアのセットを使うということができるでしょう。

サービスディスカバリには、clientTlsIdentityが設定されている必要があります。これは、アプリケーションと情報を交換するピアが、情報を交換する相手が信頼している主体であると確信する必要があるためです。もし、clientTlsIdentityが設定されていなければ、discoveryは、セットされているかに関わらず無視されるでしょう。

アプリケーションは、コネクションオプションをゲートウェイに接続する際に指定することができますが、管理者によってこれらのオプションを上書きすることが必要になることがあります。これは、オプションが時間経過によって変化しうるネットワーク上でのやりとりにかかわるからです。例えば、管理者がサービスディスカバリによるネットワーク性能に対する影響を調べようとする場合です。

よいアプローチとしては、アプリケーションがゲートウェイへの接続を設定するときに読む設定ファイルにアプリケーションごとの上書きを定義することです。

ディスカバリに関するオプションであるenabledとasLocalhostは最も頻繁に管理者によって上書きすることが必要になるため、INITIALIZE-WITH-DISCOVERYとDISCOVERY-AS-LOCALHOST環境変数が簡単のために提供されています。管理者は、アプリケーションの本番ランタイム環境ではこれらを設定すべきです。これは、Dockerコンテナであることが最も多いでしょう。