protocol.ja.txt

----------------------------------------------------------------------------
handlersocketの通信プロトコル

----------------------------------------------------------------------------
基本的な構文

・HandlerSocketのプロトコルは行ベース。各行は改行文字(0x0a)で終わる。
・各行は複数のトークンからなり、トークン間はTAB文字(0x09)で区切られる。
・トークンはNULLトークンか、文字列トークンのいずれか。
・NULLトークンは単一のNUL文字(0x00)であらわされる。
・文字列トークンは、0バイト以上の文字列であらわされる。ただし0x10未満の文字
  については0x01を前置し、0x40を加えたコードであらわされる。それ以外の文字は
  その文字自身のコードであらわされる。

----------------------------------------------------------------------------
リクエストとレスポンス

・HandlerSocketのプロトコルは単純なリクエスト・レスポンスプロトコルになって
  いる。接続が確立した後は、まずクライアントがリクエストを送る。
・サーバは、クライアントが送ったリクエストと丁度同じ数の行(レスポンス)を返
  す。
・リクエストはパイプライン化してよい。つまりクライアントは前に送ったリクエス
  トに対する返事(レスポンス)を待たずに次のリクエストを送ってもよい。

----------------------------------------------------------------------------
インデックスを開く

open_index命令は次のような構文を持つ。

    P <indexid> <dbname> <tablename> <indexname> <columns> [<fcolumns>]

- <indexid>は数字で、同一接続上で後に実行する命令の、対象索引を指定するため
  に使われる。
- <dbname>, <tablename>, <indexname>は文字列で、それぞれDB名、テーブル名、
  索引の名前を指定する。<indexname>として「PRIMARY」を指定するとプライマリ
  キーが開かれる。
- <columns>はカンマ区切りの列名のリスト。
- <fcolumns>はカンマ区切りの列名のリスト。これは省略することができる。

このopen_index命令が実行されると、HandlerSocketプラグインは指定されたDB、
テーブル、索引を開く。開かれた索引は接続が閉じられるまで開かれたままになる。
開かれた索引は<indexid>の数字で識別される。もし既に<indexid>に指定された番号
の索引が既に開かれている場合は古いほうが閉じられる。この<indexid>はなるべく
小さな数字を使ったほうが効率が良い。

----------------------------------------------------------------------------
データ取得

find命令は次のような構文を持つ。

    <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...]

LIMは次のようなパラメータの並び

    <limit> <offset>

INは次のようなパラメータの並び

    @ <icol> <ivlen> <iv1> ... <ivn>

FILTERは次のようなパラメータの並び

    <ftyp> <fop> <fcol> <fval>

- <indexid>は数字で、これは同じ接続上で過去に実行したopen_index命令に指定さ
  れた数字でなければならない。
- <op>は比較演算子で、現在のバージョンでは '=', '>', '>=', '<', '<=' をサ
  ポートしている。
- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。この値は対応するopen_index
  命令の<indexname>パラメータで指定された索引のキー列の数と同じか小さいもの
  でなければならない。
- <v1> ... <vn>は取得するべきキーの値を指定するパラメータ。
- LIMは省略できる。<limit>と<offset>は数字で、これはSQLのLIMITと同じように
  はたらく。省略した場合は1と0を指定した場合と同じ動作をする。FILTERによっ
  て読み飛ばされたレコードは<limit>と<offset>にカウントされない。
- INは省略できる。指定されると、これはSQLの WHERE ... IN のように動作する。
  <icol>は対応するopen_index命令の<indexname>パラメータで指定された索引の
  キー列の数より小さいものでなければならない。INが指定されたときは、find命
  令の<v1> ... <vn>のうち<icol>番目の値は無視される。
- FILTERは省略できる。これは行取得の際のフィルタを指定する。<ftyp>は
  'F'(filter)か'W'(while)のいずれかでなければならない。<fop>は比較演算子。
  <fcol>は数字で、これは対応するopen_index命令の<fcolumns>で指定された列の
  数より小さいものでなければならない。複数のフィルタを指定することもでき、
  その場合は各フィルタのANDと解釈される。'F'と'W'の違いは、条件にあてはま
  らない行があったときに'F'は単にそれをスキップするが、'W'はその時点でルー
  プを抜けるという点。

----------------------------------------------------------------------------
更新と削除

find_modify命令は次のような構文を持つ。

    <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...] MOD

MODは次のようなパラメータの並び

    <mop> <m1> ... <mk>

- <mop>は'U', '+', '-', 'D', 'U?', '+?', '-?', 'D?'のいずれか。'?'が付いた
  ものは付いていないものとほぼ同じ動作をするが、付いていないものがレスポン
  スとして更新された行の数を返すのに対し、付いているものは更新される前の行
  の内容を返す点のみが異なる。'U'は更新、'D'は削除、'+'はインクリメント、
  '-'はデクリメントを実行する。
- <m1> ... <mk>はセットされる各列の値。<m1> ... <mk>の長さは対応する
  open_index命令の<columns>の長さと等しいか小さくなければならない。<mop>が
  'D'のときはこれらのパラメータは無視される。<mop>が'+'か'-'のときは、これら
  の値は数値でなければならない。<mop>が'-'で、それが負数から正数、または正数
  から負数へ列の値を変更するようなものであった場合は、値は変更されない。

----------------------------------------------------------------------------
行の挿入

insert命令は次のような構文を持つ。

    <indexid> + <vlen> <v1> ... <vn>

- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。これは対応するopen_indexの
  <columns>の長さに等しいか小さくなければならない。
- <v1> ... <vn>はセットされる各列の値。指定されないかった列についてはその列
  のデフォルト値がセットされる。

----------------------------------------------------------------------------
認証

auth命令は次のような構文を持つ。

    A <atyp> <akey>

- <atyp>は現在のバージョンでは'1'のみが有効。
- 指定された<akey>が、サーバの設定の'handlersocket_plain_secret'や
  'handlersocket_plain_secret_wr'に指定された文字列と一致した場合にのみ認証
  は成功する。
- HandlerSocketの認証が有効になっているときは、この'auth'が成功しない限りそ
  れ以外の命令は全て失敗する。

----------------------------------------------------------------------------
open_indexに対するレスポンス

open_index命令が成功したとき、レスポンスは次の構文を持つ。

    0 1

----------------------------------------------------------------------------
findに対するレスポンス

find命令が成功したとき、レスポンスは次の構文を持つ。

    0 <numcolumns> <r1> ... <rn>

- <numcolumns>はfind命令の対応するopen_index命令に指定した<columns>の長さに
  一致する。
- <r1> ... <rn>は結果セット。もしN行がfind命令で見つかったなら、<r1> ...
  <rn>の長さは ( <numcolumns> * N )になる。

----------------------------------------------------------------------------
find_modifyに対するレスポンス

find_modify命令が成功したとき、レスポンスは次の構文を持つ。

    0 1 <nummod>

- <nummod>は変更された行の数。
- 例外として、<mop>が'?'の付いたものであった場合には、find命令に対するレスポ
  ンスと同じ構文のレスポンスを返す。

----------------------------------------------------------------------------
insertに対するレスポンス

insert命令が成功したとき、レスポンスは次の構文を持つ。

    0 1

----------------------------------------------------------------------------
authに対するレスポンス

auth命令が成功したとき、レスポンスは次の構文を持つ。

    0 1