Interfaces 1.1

インターフェースに関する規約

JSON ベースである事に関しての制約

• JSON として解釈可能でなければならない
• JSON の最外部はオブジェクト{ }ではなく配列[ ]でなければならない
• JSON を意味する文字列の末尾には改行 \r\n がなければならない、
  かつ途中に改行 \r\n があってはならない。すなわち、「1 行 1 JSON」であること。

構文に関する規約

以下で記述される JSON サンプルは、可視性を考慮して複数行にまたいで表記することがある。
しかし、先の規約の通り実際の文字列データでは末尾にのみ、改行がある事。

基本構文

[ "1.1", <direction>, <opecode>, <operand> ]\r\n

要素名	種類	意味
第1要素	文字列	バージョンを表す、 “1.1” 固定。
第2要素	文字列	コマンド(リクエスト)の場合は “C” レスポンスの場合は “R” が指定される
第3要素	文字列	コマンドの種類を表す文字列
第4要素	オブジェクト	各々のコマンドに与える

インターフェース詳細

---

エラーレスポンスについて

レスポンスの に要素 “error” が存在する場合、エラーレスポンスである。
エラーレスポンスを表す “error” 要素以外には、何が定義されていても良い

{ "code": <error code>, "message": <error message> }

• “code” – エラーコード、例外クラス名等
• “message” – エラーメッセージ

例1 (CREATE コマンドに対して、エラーレスポンスを返す)

[
  "1.1",
  "C",
  "CREATE",
  { "basket": "123.0.2", "hints": { "class": "original", "length": 1234 } }
]\r\n

[ 
  "1.1",
  "R",
  "CREATE",
  { "error": { "code": "JSON::ParserError", "message": "unexpected token at 'hoge'" } }
]\r\n

例2 ( “error” 要素があれば、他に何の要素があろうが不問 )

下記レスポンスはエラーである、 “basket” や “hosts” 要素が在っても、 “error” 要素があればエラーとする

[ 
  "1.1",
  "R",
  "CREATE",
  { "error": { "code": "JSON::ParserError", "message": "unexpected token at 'hoge'" },
    "basket": "123.0.2",
    "hosts": [ "std100", "std101", "std102" ]
  }
]\r\n

---

コマンド解析不可能

コマンドが正しいフォーマットのデータでなかった場合に返される、第３要素に null が与えられる。

[ "1.1", "R", null, { } ]\r\n

※ 大抵の場合 “error” 要素が付加される。
[ "1.1", "R", null, { "error": { "message": "unknown command format." } } ]\r\n

---

リクエストのサンプル

以下のコマンド詳細では第４要素以外は省略している。完全な例を示す。

[ 
  "1.1",
  "C",
  "CREATE",
  { "basket": "987654321.1.2", 
    "hints": { "class": "original", "length": 456789 }
  }
]\r\n

---

第4要素のオブジェクトに、未知のキーが与えられた場合

無視する。 (エラーにしない)

["1.1","C","NOP",{"foo":"bar","hoge":"fuga","baz":1}]

上記の foo, hoge, baz は未定義のキーであるため、無視される

---

NOP – No operation

リクエスト

{ }

レスポンス

{ }

---

CREATE – コンテンツの追加

リクエスト

{ "basket": <basket key>, 
  "hints": {
    "class": <class>, 
    "length": <length>
  }
}

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“hints”	必須	バスケットを格納するPeer判定のヒント情報	{ “class”: “original”, “length”: 456789 }
“class”	必須	コンテンツの種類	“original”
“length”	必須	コンテンツ格納に要する容量 (Byte)	123456

レスポンス (主にGateway から)

{ "basket": <basket key>, "hosts": [ <host1>, <host2>, ..., <hostN> ], "island": <islandId> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“hosts”	必須	バスケット格納可能なホストを表す配列	[ “std100”, “std101”, “std102” ]
“island”	任意	castoro の島を表す文字列	“island01”

レスポンス (Peer から)

{ "basket": <basket key>, "host": <host>, "path": <path> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“host”	必須	peer のホスト名	“std100”
“path”	必須	作業ディレクトリ	“/expdsk/1/baskets/w/20100823T15/1.1.2.20100823T150050.885.050240”

---

FINALIZE – コンテンツ作成の完了

リクエスト

{ "basket": <basket key>, "host": <host>, "path": <path> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“host”	必須	peer のホスト名	“std100”
“path”	必須	作業ディレクトリ	“/expdsk/1/baskets/w/20100823T15/1.1.2.20100823T150050.885.050240”

レスポンス

{ "basket": <basket key> }

“basket”

必須

バスケットキー文字列

“987654321.1.2”

---

CANCEL – コンテンツ作成の取消

リクエスト

{ "basket": <basket key>, "host": <host>, "path": <path> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“host”	必須	peer のホスト名	“std100”
“path”	必須	作業ディレクトリ	“/expdsk/1/baskets/w/20100823T15/1.1.2.20100823T150050.885.050240”

レスポンス

{ "basket": <basket key> }

“basket”

必須

バスケットキー文字列

“987654321.1.2”

---

GET – コンテンツの取得

リクエスト

{ "basket": <basket key>, "island": <islandId> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“island”	任意	castoro の島を表す文字列	“island01”

レスポンス

{ "basket": <basket key>, 
  "paths" : { <host1>: <path1>, ... <hostN>: <pathN> },
  "island": <islandId>
}

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“paths”	必須	ホストとそのパスを表すハッシュ	{ “std100”: “/expdsk/0/baskets/a/0/987/654/987654321.1.2”, “std101”, “/expdsk/0/baskets/a/0/987/654/987654321.1.2” }
“island”	任意	castoro の島を表す文字列	“island01”

---

DELETE – コンテンツの削除

リクエスト

{ "basket": <basket key> }

“basket”

必須

バスケットキー文字列

“987654321.1.2”

レスポンス

{ "basket": <basket key> }

“basket”

必須

バスケットキー文字列

“987654321.1.2”

---

INSERT – コンテンツ登録/更新通知

リクエスト

{ "basket": <basket key>, "host": <host>, "path": <path> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“host”	必須	peer のホスト名	“std100”
“path”	必須	バスケットを保持するパス	“/expdsk/0/baskets/a/0/987/654/987654321.1.2”

レスポンス

無し

---

DROP – コンテンツ削除通知

リクエスト

{ "basket": <basket key>, "host": <host>, "path": <path> }

“basket”	必須	バスケットキー文字列	“987654321.1.2”
“host”	必須	peer のホスト名	“std100”
“path”	必須	バスケットを保持するパス	“/expdsk/0/baskets/a/0/987/654/987654321.1.2”

レスポンス

無し

---

ALIVE – 運転状態の通知 (WatchDog)

リクエスト

{ "host": <host>, "status": <status code>, "available": <disk available Bytes> }

“host”	必須	peerのホスト名	“std100”
“status”	必須	watchdog ステータスコード	30
“available”	必須	ディスク使用可能容量(Byte)	123456789

レスポンス

無し

---

ISLAND – 島の統計情報の通知 (WatchDog)

リクエスト

{ "island": <islandId>, "storables": <storables>, "capacity": <capacity bytes> }

“island”	必須	castoroの島を表す文字列	“island01”
“storables”	必須	Basket保存可能Peer数	15
“capacity”	必須	Basket保存可能Peerの空き容量合計	12345678

レスポンス

無し

---

STATUS – サーバ情報の取得

リクエスト

{ }

レスポンス

{ "status": { <key>: <value>, <key>: <value>, ... , <key>: <value> } }

“status”

必須

サーバ情報を表すオブジェクト。任意のキー、任意の値からなる。値は 数値、文字列、true, false、null のいずれか

---

MKDIR – ディレクトリの作成 ( castoro-manipulator で使用する )

リクエスト

{ "mode": <mode>, "user": <user>, "group": <group>, "source": <source> }

“mode”	必須	ディレクトリのパーミッション (8進数表現文字列、先頭ゼロ無し)	“775”
“user”	必須	ディレクトリのオーナ	“castoro”
“group”	必須	ディレクトリのグループ	“castoro”
“source”	必須	作成するディレクトリのパス文字列	“/path/to/directory”

レスポンス

{ }

---

MV – ディレクトリの移動 ( castoro-manipulator で使用する )

リクエスト

{ "mode": <mode>, "user": <user>, "group": <group>, "source": <source>, "dest": <dest> }

“mode”	必須	ディレクトリのパーミッション (8進数表現文字列、先頭ゼロ無し)	“775”
“user”	必須	ディレクトリのオーナ	“castoro”
“group”	必須	ディレクトリのグループ	“castoro”
“source”	必須	移動元ディレクトリのパス文字列	“/path/to/directory”
“dest”	必須	移動先ディレクトリのパス文字列	“/path/to/directory”

レスポンス

{ }

---