SPN

SPN は Chip-in 内部で閉鎖されたプライベートなネットワークで、 mTLS 認証によって相互認証し、暗号化されます。 SPN Hub を中心として SPN エンドポイントから QUIC プロトコルで接続することで仮想的なネットワークを構築します。 QUIC上のストリームを TCP コネクションとして使用することで、TCP 通信と互換性を持っており、 SPN エージェントを使用することでマイクロサービス間でTCP通信を行えます。

SPNSessions

上記はユーザが API Gateway にアクセスし、それがプロキシされて SPN 経由でロジックサービスにアクセスし、ロジックサービスが SPN 経由でDBMSにアクセスする様子を表しています。

SPN Hub

SPN Hub では SPN エンドポイントからの QUIC での接続を受け付けて、仮想的で閉じたネットワークを提供します。

SPN エンドポイント

SPN エンドポイントは QUIC で SPN Hub に接続するクライアントです。SPNエンドポイントは SPN create を使用して rust で開発することが可能です。また、SPN エージェントを利用して、TCPのクライアント/サーバにも接続できます。

SPN セッション

SPN セッションは QUIC のコネクションと同義ですが、SPNのコネクションとの混同を避けるためにあえて、SPN セッションと呼びます。この他に Chip-in では HTTP のセッションやコネクションも登場しますが、それらとも区別してください。

QUIC コネクション確立後、最初に SPN エンドポイントから SPN Hub に向かって制御ストリームを開始します。制御ストリームの最初の通信として SPN エンドポイントはSPN hub に SPN セッション確立要求を送信します。 SPN Hub は、セッション確立要求が SPN 内のサービス定義に照らし合わせて許容されていれば SPN エンドポイントにACKを返すとともに SPN セッションオブジェクトをメモリ上に作成します。セッション確立後も制御ストリームは接続した状態となり、さまざまな制御パケットの通信に使用されます。

SPN セッションオブジェクトには以下が保持されます。

項目名	説明
startAt	セッション開始時刻
spnSessionId	セッションID（QUIC のサーバ側コネクションIDを使用する）
spnEndPoint	QUICコネクションの確立に使用されたクライアント証明書の Subject の値
endPointType	"serviceProvider", "serviceConsumer" のいずれか
serviceUrn	セッションのサービスのエンドポイントのURN
totalConnectionCount	このセッション上で作成された SPNコネクションの総数

SPN　セッションはセッションの開設時と終了時にログを出力します。ログの項目は以下の通り。

項目名	説明
timestamp	イベント発生時刻（ログの出力時刻と異なる場合があるのでイベント発生時の時刻を記録する）
spnSessionId	セッションID（QUIC のサーバ側コネクションIDを使用する）
spnEndPoint	QUICコネクションの確立に使用されたクライアント証明書の Subject の値
eventType	"startSpnSession", "endSpnSession" のいずれか
endPointType	"serviceProvider", "serviceConsumer" のいずれか
serviceUrn	セッションのサービスのURN
totalConnectionCount	このセッション上で作成された SPNコネクションの総数。endSpnSession のときのみ出力される
elapsedTime	セッション開設時からの経過時間。endSpnSession のときのみ出力される
terminateReason	セッションの終了理由。"shutdown", "terminatedByPeer", "error" のいずれか。endSpnSession のときのみ出力される

SPN コネクション

SPN コネクションは QUIC のコネクションと異なり、serviceConsumer エンドポイントから SPN Hub を経由して serviceProvider エンドポイントに接続するストリームです。 SPN コネクションは以下の構成要素からなります。

serviceConsumer エンドポイントと SPN Hub の間の双方向 QUIC ストリーム
SPN Hub と serviceProvider エンドポイントの間の双方向 QUIC ストリーム
SPN コネクション管理オブジェクト

SPNコネクションの確立は

serviceConsumer エンドポイントは SPN Hub との間の双方向 QUIC ストリーム上に最初のパケットを送る
SPN Hub は serviceProvider エンドポイントとの間の双方向 QUIC ストリーム上にそのパケットを転送する SPN コネクションオブジェクトには以下が保持されます。

項目名	説明
startAt	コネクション開始時刻
spnConnectionId	SPNコネクションID（QUIC のストリームIDを serviceConsumer側、serviceProvider側の順に連結したものを使用する）
consumerSideSpnSessionId	serviceConsumer側 SPN セッションのID
providerSideSpnSessionId	serviceProvider側 SPN セッションのID
totalSentBytes	このストリーム上で serviceConsumerからserviceProviderに送信したデータの累計バイト数
totalReceiveBytes	このストリーム上で serviceConsumer がserviceProviderから受信したデータの累計バイト数

SPN　セッションはセッションの開設時と終了時にログを出力します。ログの項目は以下の通り。

項目名	説明
timestamp	イベント発生時刻（ログの出力時刻と異なる場合があるのでイベント発生時の時刻を記録する）
spnConnectionId	SPNコネクションID（QUIC のストリームIDを serviceConsumer側、serviceProvider側の順に連結したものを使用する）
eventType	"startSpnConnection", "endSpnConnection" のいずれか
consumerSideSpnSessionId	serviceConsumer側 SPN セッションのID
providerSideSpnSessionId	serviceProvider側 SPN セッションのID
totalSentBytes	このストリーム上で serviceConsumerからserviceProviderに送信したデータの累計バイト数。 endSpnConnection のときのみ出力される
totalReceiveBytes	このストリーム上で serviceConsumer がserviceProviderから受信したデータの累計バイト数。 endSpnConnection のときのみ出力される
elapsedTime	コネクション開設時からの経過時間。 endSpnConnection のときのみ出力される
disconnectReason	コネクションの切断理由。"closedByPeer", "closed", "error" のいずれか。 endSpnConnection のときのみ出力される

spnhub コマンド

spnhub コマンドは SPN Hub を実装します。spnhub コマンドのパラメータはコマンドラインオプションと環境変数のいずれかで指定できます。パラメータには以下のものがあります。

オプション	環境変数名	説明	デフォルト
-c	SPNHUB_INVENTORY_URL	SPN Hub の構成情報を提供するインベントリのURL。	http://localhost:8080

spnhubコマンドは起動時とリロードシグナル受信時に構成情報をインベントリから読み込みます。具体的には以下の順に読み込みます。リロードシグナルは SIGUSR1 です。

1. レルムの読み込み

全てのレルムを読み込みます。 SPN Hub はレルムごとに内部が分離されており、マルチテナントのシステムを容易に実装できます。

name required	string レルムの名前。URN の一部として使用される。文字列は小文字英字、数字、ハイフン、アンダースコアのみを含むことができる。
title required	string レルムの日本語名称です。
description	string レルムの説明文です。
cacert required	string realm 配下の SPN hub で mTLSにおけるクライアント証明書を発行したCA局の証明書(PEM形式)の文字列
administrators	Array of strings レルムの管理者のユーザID。ユーザの管理はインベントリでは行わない。認証サービス内でのみ管理され、ここではそのIDのみを参照する。
expiredAt	string <date-time> レルムの有効期限。ISO8601形式で指定する。この日時を過ぎると、レルムの disabled フラグは true となり、関連するリソースへのアクセスが制限される。
disabled required	boolean レルムが無効化されているかどうかを示すフラグ。 true の場合、レルムは無効化されており、関連するリソースへのアクセスが制限される。 false の場合、レルムは有効であり、通常の操作が可能である。

disabled が True のものは無視します。
リロードにおいては、一覧の前後を比較し、追加削除を行います。

2. SPN Hub の構築

レルムごとに SPN Hub を構築します。

name required	string SPN Hub の名前。URN の一部として使用される。文字列は小文字英字、数字、ハイフン、アンダースコアのみを含むことができる。
realm required	string SPN Hub が属する realm の名前。URN の一部として使用される。
urn required	string SPN Hub のURN。URNは、SPN Hubを一意に識別するための文字列で、以下の形式で構成される。 urn:chip-in:network:{realm}:{name}
title required	string SPN Hub の日本語名称です。
description	string SPN Hub の説明文です。
fqdn required	string SPN Hub のサーバのFQDN
serverPort	integer SPN Hub のサーバのポート番号。デフォルトは 443
serverCert required	string mTLSにおけるサーバ証明書(PEM形式)の文字列。 SPN Hub のサーバは、この証明書を使用してクライアントとの通信を暗号化する。
serverCertKey required	string mTLSにおけるサーバ証明書の秘密鍵(PEM形式)の文字列。 SPN Hub のサーバは、この秘密鍵を使用してクライアントとの通信を暗号化する。

3. サービスの構築

SPN Hub ごとにサービスの定義を読み込みます。

name required	string サービスの名前。URN の一部として使用される。文字列は小文字英字、数字、ハイフン、アンダースコアのみを含むことができる。
urn required	string サービスのURN。URNは、サービスを一意に識別するための文字列で、以下の形式で構成される。 urn:chip-in:service:{realm}:{hubName}:{name}
title required	string サービスの日本語名称です。URN の一部として使用される。文字列は日本語を含むことができる。
description	string サービスの説明文です。URN の一部として使用される。文字列は日本語を含むことができる。
realm required	string サービスが属するレルムの名前。
hubName required	string サービスが接続される SPN Hub の名前。 SPN Hub は、サービスの提供を行うためのネットワークハブであり、サービスへのアクセスを管理する。
	object コンテナクラスタ内でマイクロサービスのスケジュール起動、オンデマンド起動を行うためのパラメータ
providers required	Array of strings 当該サービスの提供が許可されるエンドポイントクライアント証明書の Subject の値と照合される
consumers required	Array of strings 当該サービスの利用が許可されるエンドポイントクライアント証明書の Subject の値と照合される

availabilityManagement が指定されていて、かつ ondemandStart が false のサービスについてはクラスタマネージャを呼び出してサービスを起動する。サービス定義の読み込みが終わった時点で、SPN Hub での QUIC パケットの受信を開始します。

SPN エンドポイント crate

概要

この crate は SPN (Service Provider Network) のエンドポイントを提供します。
SPN セッションの確立と、双方向ストリームによる通信をサポートします。

Consumer エンドポイント

`createSpnConsumerEndPoint`関数

async fn createSpnConsumerEndPoint(
    spnHubUrl: &str,
    serviceUrn: &str,
    certificate: &str,
    certificate_key: &str
) -> Result<impl spnConsumerEndPoint, SpnError>

引数
- spnHubUrl: SPN ハブの URL
- serviceUrn: サービスの URN
- certificate: PEM形式のクライアント証明書
- certificate_key: PEM形式のクライアント証明書の秘密鍵
戻り値
SPN セッションが確立された spnConsumerEndPoint インタフェースのハンドル。エラー時は SpnError。
主なエラー例
- クライアント証明書の読み込み失敗
- ネットワークエラー
- SPN Hub からの拒否

`spnConsumerEndPoint` インタフェース

メソッド
- async fn connect(&self, stream: BiDirectionalStream) -> Result<(), SpnError>
  - 呼び側が事前に準備した双方向ストリームをSPNコネクションに接続する。エラー時は SpnError。

利用例

let endpoint = createSpnConsumerEndPoint(
    "https://spn-hub.example.com",
    "urn:chip-in:service:example-realm:foo",
    "/path/to/cert.pem"
).await?;

let my_stream = BiDirectionalStream::new(/* ... */);
endpoint.connect(my_stream).await?;
// my_stream を使って双方向通信を行う

Provider エンドポイント

`createSpnProviderEndPoint`

async fn createSpnProviderEndPoint(
    spnHubUrl: &str,
    serviceUrn: &str,
    certificate: &str,
    certificate_key: &str
) -> Result<impl spnProviderEndPoint, SpnError>

引数
- spnHubUrl: SPN ハブの URL
- serviceUrn: サービスの URN
- certificate: PEM形式のクライアント証明書
- certificate_key: PEM形式のクライアント証明書の秘密鍵
戻り値
SPN セッションが確立された spnProviderEndPoint インタフェースのハンドル。エラー時は SpnError。
主なエラー例
- プロバイダ証明書の読み込み失敗
- ネットワークエラー
- SPN Hub からの拒否

`spnProviderEndPoint` インタフェース

メソッド
- async fn listen(&self) -> Result<spnProviderRequest, SpnError>
  - 新たな SPN コネクションの接続を待ち受け、接続されると spnProviderRequest インタフェースを返す。エラー時は SpnError。

`spnProviderRequest` インタフェース

メソッド
- async fn accept(&self) -> Result<BiDirectionalStream, SpnError>
  - SPN コネクションを接続し、双方向ストリームを返す。エラー時は SpnError。

利用例

let provider = createSpnProviderEndPoint(
    "https://spn-hub.example.com",
    "urn:chip-in:service:example-realm:foo",
    "/path/to/cert.pem"
).await?;

let request = provider.listen().await?;
let stream = request.accept().await?;
// stream を使って双方向通信を行う

SPN エージェント

SPN エージェントは SPN Hub に接続し、SPN セッションを確立するためのエージェントです。 SPN Comsumer エージェントと SPN Provider エージェントの2つのタイプがあります。

SPN Consumer エージェント

SPN Consumer エージェントは SPN Hub に接続し、SPN セッションを確立するためのエージェントです。パラメータは環境変数で指定します。指定できる環境変数は以下の通りです。

環境変数名	説明	値の例
SPN_HUB_URL	SPN Hub の URL	`https://spn-hub.example.com`
SPN_SERVICE_URN	サービスの URN	`urn:example:service`
SPN_CERTIFICATE	クライアント証明書	PEM形式のクライアント証明書
SPN_CERTIFICATE_KEY	クライアント証明書秘密鍵	PEM形式のクライアント証明書の秘密鍵
BIND_ADDRESS	エージェントが listen するバインドアドレス	`127.0.0.11:8080`

起動すると、SPN Hub に接続し、SPN セッションを確立します。 BIND_ADDRESS にクライアントからの接続があるごとに、SPN Hub 経由でSPNコネクションを確立しサービスのプロバイダに接続します。

SPN Provider エージェント

SPN Provider エージェントは SPN Hub に接続し、SPN セッションを確立するためのエージェントです。パラメータは環境変数で指定します。指定できる環境変数は以下の通りです。

環境変数名	説明	値の例
SPN_HUB_URL	SPN Hub の URL	`https://spn-hub.example.com`
SPN_SERVICE_URN	サービスの URN	`urn:example:service`
SPN_CERTIFICATE	クライアント証明書	PEM形式のクライアント証明書
SPN_CERTIFICATE_KEY	クライアント証明書秘密鍵	PEM形式のクライアント証明書の秘密鍵
FORWARD_ADDRESS	SPN Hub からの接続を転送するアドレス	`127.0.0.1:8080`

起動すると、SPN Hub に接続し、SPN セッションを確立します。 SPN Hub からの接続を待ち受け、接続があるごとに、SPN Hub 経由でSPNコネクションを確立し FORWARD_ADDRESS にプロキシ転送します。

SPN Hub​

SPN エンドポイント​

SPN セッション​

SPN コネクション​

spnhub コマンド​

1. レルムの読み込み​

2. SPN Hub の構築​

3. サービスの構築​

SPN エンドポイント crate​

概要​

Consumer エンドポイント​

createSpnConsumerEndPoint関数​

spnConsumerEndPoint インタフェース​

利用例​

Provider エンドポイント​

createSpnProviderEndPoint​

spnProviderEndPoint インタフェース​

spnProviderRequest インタフェース​