サーバAPI (Version 1)

サーバ関連の操作を提供するAPI。

リンク:

• API定義のソースファイル

• API Blueprint

用語 ¶

サーバ:

• frugalosプロセスのこと

• 各サーバは、クラスタ内で一意なIDを有している

バケツ:

• バケツとは、オブジェクト群を格納するための入れ物

• オブジェクトの名前空間は、バケツ毎に異なる

• 冗長化方式等の設定は、バケツ毎に異なるものを設定可能

• バケツ内の領域は、作成時に指定された数のセグメントに(論理的に)分割されている

• 一つのバケツには、一つのデバイスが対応する

  • オブジェクト群は、そのデバイスに格納される
  • デバイスに関する詳細は デバイスAPI を参照のこと

• なお__systemという名前のバケツが、システム用に予約されている(i.e., 最初から存在し削除は不可)

セグメント:

• バケツの論理的な分割単位

• セグメント数は、バケツ作成時に指定されて、その後変更は不可

• 一つのバケツは、典型的には千個程度のセグメントに分割される

• オブジェクト一覧を取得したい場合を除いて、基本的には利用者が意識する必要はない

オブジェクト:

• オブジェクトとは、IDとそれに対応する内容、およびバージョンから構成されるデータ

• あるオブジェクトは、いずれかのバケツに格納され、そのIDはバケツ内で一意である

• あるオブジェクトのバージョンは、保存(PUT)毎に自動で割り当てられ、その値は単調増加することが保証されている

  • 値が1ずつ増加する保証はない
  • このバージョンの値を利用することで、いわゆるCAS(Compare And Swap)的な操作が可能となる

• オブジェクトの内容としては、任意のバイト列を格納可能

  • ただし、構成・設定に応じて、最大サイズには上限が設けられる
  • 具体的な上限は設定に依存するが、通常は数十MB程度となる
  • TODO: 使用しているバケツでの上限は TODO のAPIを叩くことで取得可能

オブジェクトプレフィックス:

• バケツに登録されているオブジェクトに付与されているIDの接頭辞

• 接頭辞であるので、あるオブジェクトに対してオブジェクトプレフィックスは複数存在する

  • 例えば lv12 のオブジェクトプレフィックスは l, lv, lv1, lv12 となる

デッドライン:

• オブジェクト関連の操作では、その完了までに要する時間の期待上限値が指定可能である

  • この値のことをデッドラインと呼称する

• デッドラインが指定された操作は、極力その時間内で実行が完了するようにスケジューリングされる

• ただし、その時間内で確実に完了する保証はなく、またそれを超過したからといって実行が中断されることもない

  • つまり一種の優先度的な値

• 即時に実行する必要がない操作に関しては、デッドラインを長めに指定することで、他のより緊急度の高い操作を優先されることが可能

デバイス:

• オブジェクト群の物理的な格納先

• デバイスには大別して 物理デバイス と 仮想デバイス の二種類が存在する

• 物理デバイス:

  • HDDやSSD等の物理的なデバイス
  • 各物理デバイスは、特定の サーバ に属する
  • 物理デバイスの種別は、その実体に応じてmemoryやmonofileといったようにさらに細分化される

• 仮想デバイス (type=virtual):

  • 物理デバイスをグルーピングする仮想的なデバイス
  • 「マシン」、「ラック」、「データセンタ」といった単位は仮想デバイスを用いて表現する

• type=memory:

  • 全てのオブジェクトをメモリ上に保持する

• type=monofile:

  • オブジェクト群を単一ファイル上に保持する

• サーバが保持するオブジェクト群を物理的に保持するための装置

  • e.g., HDD, SSD

• 各サーバへのデバイスの追加はデバイスAPI経由で行う

重み (Weight):

• デバイスをセグメントに割り当てる際の重み

• 各デバイスは、この値に比例した数のセグメントを担当することになる

• デフォルト値は、デバイスの種別によって異なる:

  • memory: 1
  • monofile: capacity_gbの値
  • virtual: childrenの重みの合計値

デバイスの無効化:

• enableフラグをfalseに設定することで、一時的にそのデバイスの使用を停止することができる

• これは機能的にはデバイスの削除と似ているが、以下の点が異なる:

  • デバイスが無効化された場合には、そのデバイスが担当していたセグメント群のみを、他のデバイス群が肩代わりする
    • つまり、データの移動は発生するが、その量は最小限で済む
    • => 短期的に取り外しているだけなら、こちらの方が良い
  • 逆に、デバイスを削除した場合には、クラスタ全体でのセグメント群の割り当てが最適化されるように割振りの調整が行われる
    • つまり、データの移動量は若干増えるが、それが完了した後のバランスぐらいは最適なものとなる
    • => 永続的に削除するなら、こちらの方が良い

共通仕様 ¶

エラー時の応答:

• エラー時の応答形式はRFC 7807に準拠する

• 各エンドポイントで固有の意味を持つ応答ステータスコードに関しては、この文書内で明示的に定義している

• それ以外のエラー応答に関しては、HTTPの一般的なセマンティクスに従い、この文書内で定義することはしない

  • e.g., 応答ステータスが500なら、サーバ内部エラー

Content-Type: application/json

[
  {
    "id": "server0"
  }
]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Content-Type: application/json

{
  "host": "10.0.2.10",
  "port": 3000,
  "devices": [
    "device0",
    "device1"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "number",
      "default": 3000
    },
    "devices": {
      "type": "array"
    }
  },
  "required": [
    "host"
  ]
}

Content-Type: application/json

{
  "host": "10.0.2.10",
  "port": 3000,
  "devices": [
    "device0",
    "device1"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "number",
      "default": 3000
    },
    "devices": {
      "type": "array"
    }
  },
  "required": [
    "host"
  ]
}

Content-Type: application/json

{
  "host": "10.0.2.10",
  "port": 3000,
  "devices": [
    "device0",
    "device1"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "number",
      "default": 3000
    },
    "devices": {
      "type": "array"
    }
  },
  "required": [
    "host"
  ]
}

Content-Type: application/problem+json

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Content-Type: application/json

{
  "host": "10.0.2.10",
  "port": 3000,
  "devices": [
    "device0",
    "device1"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "number",
      "default": 3000
    },
    "devices": {
      "type": "array"
    }
  },
  "required": [
    "host"
  ]
}

Content-Type: application/problem+json

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Content-Type: application/json

TODO