/lua-resty-etcd

Nonblocking Lua etcd driver library for OpenResty

Primary LanguagePerlApache License 2.0Apache-2.0

Name

resty-etcd Nonblocking Lua etcd driver library for OpenResty, this module supports etcd API v2.

Build Status License

Table of Contents

Install

Dependencies

install by luarocks

luarocks install lua-resty-etcd

install by source

$ luarocks install lua-resty-http lua-typeof
$ git clone https://github.com/iresty/lua-resty-etcd.git
$ cd lua-resty-etcd
$ sudo make install

Back to TOC

Method

new

syntax: cli, err = etcd.new([option:table])

  • option:table
    • host: string - default http://127.0.0.1:2379
    • ttl: int - default -1 default ttl for key operation. set -1 to disable ttl.
    • prefix: string append this prefix path string to key operation url '/v2/keys'.
    • timeout: int request timeout seconds.

The client methods returns either a HTTP Response Entity or an error string.

HTTP Response Entity contains the following fields except 408 timeout status;

  • status: number - HTTP status code.
  • header: table - response header if status is not 408 timeout status.
  • body: string or table - response body if status is not 408 timeout status.

Note: a client method will decode a response body as a JSON string if a Content-Type response header value is a application/json.

local cli, err = require('resty.etcd').new()

Please refer the etcd API documentaion at - https://github.com/coreos/etcd for more details of a response entity.

Back to TOC

get

syntax: res, err = cli:get(key:string)

Gets the value for key.

local res, err = cli:get('/path/to/key')

Back to TOC

set

syntax: res, err = cli:set(key:string, val:JSON value [, ttl:int])

Set a key-value pair.

local res, err = cli:set('/path/to/key', 'val', 10)

Back to TOC

setnx

syntax: res, err = cli:setnx(key:string, val:JSON value [, ttl:int])

Set a key-value pair if that key does not exist.

local res, err = cli:setnx('/path/to/key', 'val', 10)

Back to TOC

setx

syntax: res, err = cli:setx(key:string, val:JSON value [, ttl:int [, modified_index:uint] ])

  • modified_index: uint - this argument to use to the prev_index query of atomic operation.

Set a key-value pair when that key is exists.

local res, err = cli:setx('/path/to/key', 'val', 10)
local res, err = cli:get('/path/to/key')

-- this operation will be failed if the `modified_index` of specified key
-- has already been updated by another client.
res, err = cli:setx('/path/to/key', 'val', 10, res.body.node.modifiedIndex)

Back to TOC

delete

syntax: res, err = cli:delete(key:string [, val:JSON value [, modified_index:uint] ])

  • val: JSON value - this argument to use to the prevValue query of atomic operation.
  • modified_index: uint - this argument to use to the prev_index query of atomic operation.

Deletes a key-value pair.

local res, err = cli:delete('/path/to/key')
local res, err = cli:get('/path/to/key')

-- delete key-value pair if both of `value` and `modified_index` has matched
-- to the passed arguments
res, err = cli:delete('/path/to/key', res.body.node.value,
                      res.body.node.modifiedIndex)

-- delete key-value pair if `value` has matched to the passed value
res, err = cli:delete('/path/to/key', res.body.node.value)

-- delete key-value pair if `modified_index` has matched to the passed
-- modifiedIndex
res, err = cli:delete('/path/to/key', nil, res.body.node.modifiedIndex)

Back to TOC

wait

syntax: res, err = cli:wait(key:string [, modified_index:uint [, timeout:uint] ])

  • modified_index: uint - this argument to use to the prev_index query of atomic operation.
  • timeout: uint - request timeout seconds. set 0 to disable timeout.

Wait the update of key.

local res, err = cli:wait('/path/to/key')
local res, err = cli:get('/path/to/key')

-- Wait forever the update of key until that modifiedIndex of key has changed
-- to modifiedIndex + 1
res, err = cli:wait('/path/to/key', res.body.node.modifiedIndex + 1, 0)

-- Wait for 10 seconds the update of key until that modifiedIndex of key has
-- changed to modifiedIndex + 2
res, err = cli:wait('/path/to/key', res.body.node.modifiedIndex + 2, 10)

Back to TOC

readdir

syntax: res, err = cli:readdir(key:string [, recursive:boolean])

  • recursive: boolean - get all the contents under a directory.

Read the directory.

local res, err = cli:readdir('/path/to/dir')

Back to TOC

mkdir

syntax: res, err = cli:mkdir(key:string [, ttl:int])

Creates a directory.

local res, err = cli:mkdir('/path/to/dir', 10)

Back to TOC

mkdirnx

syntax: res, err = cli:mkdirnx(key:string [, ttl:int])

Creates a directory if that directory does not exist.

local res, err = cli:mkdirnx('/path/to/dir', 10)

Back to TOC

rmdir

syntax: res, err = cli:rmdir(key:string [, recursive:boolean])

  • recursive: boolean - remove all the contents under a directory.

Remove the directory

local res, err = cli:rmdir('/path/to/dir')

Back to TOC

waitdir

syntax: res, err = cli:waitdir(key:string [, modified_index:uint [, timeout:uint] ])

  • modified_index: uint - this argument to use to the prev_index query of atomic operation.
  • timeout: uint - request timeout seconds. set 0 to disable timeout.
local res, err = cli:waitdir('/path/to/dir')

Back to TOC

push

syntax: res, err = cli:push(key:string, val:JSON value [, ttl:int])

Pushs a value into the specified directory.

local res, err = cli:mkdir('/path/to/dir')
res, err = cli:push('/path/to/dir', 'val', 10)

Back to TOC

version

syntax: res, err = cli:version()

Gets the etcd version info.

Back to TOC

stats_leader

syntax: res, err = cli:stats_leader()

Gets the leader statistics info.

Back to TOC

stats_self

syntax: res, err = cli:stats_self()

Gets the self statistics info.

Back to TOC

stats_store

syntax: res, err = cli:stats_store()

Gets the store statistics info.

Back to TOC