From bbcaee886b1c85c41f70e0dd842fbb557ed531f7 Mon Sep 17 00:00:00 2001 From: Thibault Charbonnier Date: Fri, 11 Dec 2015 00:02:43 -0800 Subject: [PATCH] docs(readme) better example, test and tools doc --- Makefile | 2 +- README.md | 111 ++++++++++++++++++++++++--------- lua-cassandra-0.4.0-0.rockspec | 2 +- 3 files changed, 85 insertions(+), 30 deletions(-) diff --git a/Makefile b/Makefile index d829544c..278a0b8a 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ DEV_ROCKS=busted luacov luacov-coveralls luacheck ldoc -.PHONY: instal dev clean test coverage lint doc +.PHONY: install dev clean test coverage lint doc install: @luarocks make lua-cassandra-*.rockspec diff --git a/README.md b/README.md index 138660fc..17b0c3fb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,16 @@ A pure Lua client library for Apache Cassandra (2.0+), compatible with Lua and [ngx_lua]. -It is build on the model of the official Datastax drivers, and tries to implement the same behaviors and features. +It is build following the example of the official Datastax drivers, and tries to implement the same behaviors, options and features. + +## Table of Contents + +- [Features](#features) +- [Usage](#usage) +- [Installation](#installation) +- [Documentation and Examples](#documentation-and-examples) +- [Test Suite](#test-suite) +- [Tools](#tools) ## Features @@ -13,7 +22,7 @@ It is build on the model of the official Datastax drivers, and tries to implemen - Configurable load balancing, reconnection and retry policies - TLS client-to-node encryption - Client authentication -- Highly configurable options per session/request +- Highly configurable options per session/query - Compatible with Cassandra 2.0 and 2.1 - Works with Lua 5.1, 5.2, 5.3 and LuaJIT 2.x @@ -32,7 +41,7 @@ http { server { ... - location /insert { + location / { content_by_lua ' local cassandra = require "cassandra" @@ -54,23 +63,6 @@ http { -- ... end - session:set_keep_alive() - '; - } - - location /get { - content_by_lua ' - local cassandra = require "cassandra" - - local session, err = cassandra.spawn_session { - shm = "cassandra", -- defined by "lua_shared_dict" - contact_points = {"127.0.0.1"} - } - if err then - ngx.log(ngx.ERR, "Could not spawn session: ", tostring(err)) - return ngx.exit(500) - end - local rows, err = session:execute("SELECT * FROM users") if err then -- ... @@ -106,7 +98,7 @@ assert(err == nil) local rows, err = session:execute("SELECT * FROM users") assert(err == nil) -print("number of users: ", #rows) +print("rows retrieved: ", #rows) session:shutdown() ``` @@ -119,26 +111,89 @@ With [Luarocks]: $ luarocks install lua-cassandra ``` -If installed manually, this module requires: - -- [lua-cjson](https://github.com/mpx/lua-cjson/) -- [LuaSocket](http://w3.impa.br/~diego/software/luasocket/) -- If you wish to use TLS client-to-node encryption, [LuaSec](https://github.com/brunoos/luasec) +Manually: -Once you have a local copy of this module's files under `src/`, add this to your Lua package path: +Once you have a local copy of this module's `src/` fo lder, add it to your `LUA_PATH` (or `lua_package_path` for ngx_lua): ``` /path/to/src/?.lua;/path/to/src/?/init.lua; ``` +**Note**: If used *outside* of ngx_lua, this module requires: + +- [LuaSocket](http://w3.impa.br/~diego/software/luasocket/) +- If you wish to use TLS client-to-node encryption, [LuaSec](https://github.com/brunoos/luasec) + ## Documentation and examples The current [documentation] targets version `0.3.6` only. `0.4.0` documentation should come soon. +## Test Suite + +This library uses three test suites: + +- Unit tests, with busted +- Integration tests, with busted and a running Cassandra cluster +- ngx_lua integration tests with Test::Nginx::Socket + +The first can simply be run after installing [busted](http://olivinelabs.com/busted/) and running: + +```shell +$ busted spec/unit +``` + +The integration tests are located in another folder, and require a Cassandra instance to run on `localhost`: + +```shell +$ busted spec/integration +``` + +Your cluster's hosts (not just the contact points, but all of them) should be declared in the `HOSTS` environment variable: + +```shell +$ HOSTS=127.0.0.1,127.0.0.2,127.0.0.3 busted spec/integration +``` + +Finally, the ngx_lua integration tests can be run after installing the [Test::Nginx::Socket](http://search.cpan.org/~agent/Test-Nginx-0.23/lib/Test/Nginx/Socket.pm) module: + +```shell +$ prove t/ +``` + +## Tools + +This module can also use various tools for code quality, they can easily be installed from Luarocks by running: + +``` +$ make dev +``` + +Code coverage is analyzed by [luacov](http://keplerproject.github.io/luacov/) from the **busted** (unit and integration) tests: + +```shell +$ busted --coverage +$ luacov cassandra +# or +$ make coverage +``` + +The code is linted with [luacheck](https://github.com/mpeterv/luacheck). It is easier to use the Makefile again to avoid analyzing Lua files that are not part of this module: + +```shell +$ make lint +``` + +The documentation is generated by [ldoc](https://github.com/stevedonovan/LDoc) and can be generated with: + +```shell +$ ldoc -c doc/config.ld src +# or +$ make doc +``` + [ngx_lua]: https://github.com/openresty/lua-nginx-module [Luarocks]: https://luarocks.org -[lua-resty-cassandra]: https://github.com/jbochi/lua-resty-cassandra [documentation]: http://thibaultcha.github.io/lua-cassandra/ [manual]: http://thibaultcha.github.io/lua-cassandra/manual/README.md.html diff --git a/lua-cassandra-0.4.0-0.rockspec b/lua-cassandra-0.4.0-0.rockspec index 2cc31827..cff199fd 100644 --- a/lua-cassandra-0.4.0-0.rockspec +++ b/lua-cassandra-0.4.0-0.rockspec @@ -5,7 +5,7 @@ source = { tag = "0.4.0" } description = { - summary = "Lua Cassandra client library", + summary = "Feature-rich client library for Cassandra", homepage = "http://thibaultcha.github.io/lua-cassandra", license = "MIT" }