Browse files

updated docs

  • Loading branch information...
1 parent 88bf1e0 commit fc8962d9e2ceb2c3d66940cc68378113f09bc875 @ahiguti committed May 23, 2011
Showing with 75 additions and 10 deletions.
  1. +3 −0 AUTHORS
  2. +13 −1 docs-en/configuration-options.en.txt
  3. +59 −9 docs-en/protocol.en.txt
View
3 AUTHORS
@@ -17,3 +17,6 @@ Moriyoshi Koizumi (https://github.com/moriyoshi)
takeda-at (https://github.com/takada-at)
- added simple authorization function
+WheresWardy (https://github.com/WheresWardy)
+ - added authentication functions to libhsclient
+
View
14 docs-en/configuration-options.en.txt
@@ -80,8 +80,20 @@ handlersocket_accept_balance (default = 0, min = 0, max = 10000)
handlersocket_wrlock_timeout (default = 12, min = 0, max = 3600)
Specify the lock timeout in seconds. When a write request is
- performed, handlersocket locks an advisory lock named
+ performed, handlersocket acquires an advisory lock named
'handlersocket_wr'. This option sets the timeout for the
locking.
+-----------------------------------------------------------------
+handlersocket_plain_secret (default = '')
+
+ When this option is specified, a plain-text authentication is
+ enabled for the listener for read requests. This option
+ specifies the secret key for the authentication.
+
+-----------------------------------------------------------------
+handlersocket_plain_secret_wr (default = '')
+
+ This option specifies the secret key for the listener for write
+ requests.
View
68 docs-en/protocol.en.txt
@@ -33,12 +33,14 @@ Request and Response
The 'open_index' request has the following syntax.
- P <indexid> <dbname> <tablename> <indexname> <columns>
+ P <indexid> <dbname> <tablename> <indexname> <columns> [<fcolumns>]
- <indexid> is a number in decimal.
- <dbname>, <tablename>, and <indexname> are strings. To open the primary
key, use PRIMARY as <indexname>.
- <columns> is a comma-separated list of column names.
+- <fcolumns> is a comma-separated list of column names. This parameter is
+ optional.
Once an 'open_index' request is issued, the HandlerSocket plugin opens the
specified index and keep it open until the client connection is closed. Each
@@ -51,39 +53,74 @@ For efficiency, keep <indexid> small as far as possible.
Getting data
The 'find' request has the following syntax.
+
+ <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...]
- <indexid> <op> <vlen> <v1> ... <vn> <limit> <offset>
+LIM is a sequence of the following parameters.
+
+ <limit> <offset>
+
+IN is a sequence of the following parameters.
+
+ @ <icol> <ivlen> <iv1> ... <ivn>
+
+FILETER is a sequence of the following parameters.
+
+ <ftyp> <fop> <fcol> <fval>
- <indexid> is a number. This number must be an <indexid> specified by a
'open_index' request executed previously on the same connection.
- <op> specifies the comparison operation to use. The current version of
HandlerSocket supports '=', '>', '>=', '<', and '<='.
- <vlen> indicates the length of the trailing parameters <v1> ... <vn>. This
must be smaller than or equal to the number of index columns specified by
- specified by the corresponding 'open_index' request.
+ the <columns> parameter of the corresponding 'open_index' request.
- <v1> ... <vn> specify the index column values to fetch.
-- <limit> and <offset> are numbers. These parameters can be omitted. When
- omitted, it works as if 1 and 0 are specified.
+- LIM is optional. <limit> and <offset> are numbers. When omitted, it works
+ as if 1 and 0 are specified. These parameter works like LIMIT of SQL.
+ These values don't include the number of records skipped by a filter.
+- IN is optional. It works like WHERE ... IN syntax of SQL. <icol> must be
+ smaller than or equal to the number of index columns specified by the
+ <columns> parameter of the corresponding 'open_index' request. If IN is
+ specified in a find request, the <icol>-th parameter value of <v1> ...
+ <vn> is ignored.
+ smaller than or equal to the number of index columns specified by the
+- FILTERs are optional. A FILTER specifies a filter. <ftyp> is either 'F'
+ (filter) or 'W' (while). <fop> specifies the comparison operation to use.
+ <fcol> must be smaller than or equal to the number of columns specified by
+ the <fcolumns> parameter of the corresponding 'open_index' request.
+ Multiple filters can be specified, and work as the logical AND of them.
+ The difference of 'F' and 'W' is that, when a record does not meet the
+ specified condition, 'F' simply skips the record, and 'W' stops the loop.
----------------------------------------------------------------------------
Updating/Deleting data
The 'find_modify' request has the following syntax.
- <indexid> <op> <vlen> <v1> ... <vn> <limit> <offset> <mop> <m1> ... <mk>
+ <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...] MOD
+
+MOD is a sequence of the following parameters.
+
+ <mop> <m1> ... <mk>
-- <mop> is either 'U' (update) or 'D' (delete).
+- <mop> is 'U' (update), '+' (increment), '-' (decrement), 'D' (delete),
+ 'U?', '+?', '-?', or 'D?'. If the '?' suffix is specified, it returns
+ the contents of the records before modification (as if it's a 'find'
+ request), instead of the number of modified records.
- <m1> ... <mk> specifies the column values to set. The length of <m1> ...
<mk> must be smaller than or equal to the length of <columns> specified by
the corresponding 'open_index' request. If <mop> is 'D', these parameters
- are ignored.
+ are ignored. If <mop> is '+' or '-', values must be numeric. If <mop> is
+ '-' and it attempts to change column values from negative to positive or
+ positive to negative, it is not modified.
----------------------------------------------------------------------------
Inserting data
The 'insert' request has the following syntax.
- <indexid> '+' <vlen> <v1> ... <vn>
+ <indexid> + <vlen> <v1> ... <vn>
- <vlen> indicates the length of the trailing parameters <v1> ... <vn>. This
must be smaller than or equal to the length of <columns> specified by the
@@ -92,6 +129,19 @@ The 'insert' request has the following syntax.
<columns>, the default values for each column are set.
----------------------------------------------------------------------------
+Authentication
+
+The 'auth' request has the following syntax.
+
+ A <atyp> <akey>
+
+- <atyp> must be '1'
+- An 'auth' request succeeds iff <akey> is the correct secret specified by
+ the 'handlersocket_plain_secret' or 'handlersocket_plain_secret_rw'.
+- If an authentication is enabled for a listener, any other requests on a
+ connection fail before an 'auth' request succeeded on the connection.
+
+----------------------------------------------------------------------------
Response syntax
HandlerSocket returns a response of the following syntax for each request.

0 comments on commit fc8962d

Please sign in to comment.