Permalink
Browse files

docs(ldoc) helpers spec doc updates

Signed-off-by: Thibault Charbonnier <thibaultcha@me.com>
  • Loading branch information...
1 parent 417659d commit e3c1b3cdba0d73219e926f9f05ee4f32b655e5b9 Thijs Schreijer committed with thibaultcha Jul 26, 2016
Showing with 89 additions and 15 deletions.
  1. +15 −0 config.ld
  2. +2 −0 kong/dao/dao.lua
  3. +5 −1 kong/tools/responses.lua
  4. +5 −2 kong/tools/timestamp.lua
  5. +3 −0 kong/tools/utils.lua
  6. +59 −12 spec/helpers.lua
View
@@ -0,0 +1,15 @@
+project='Kong'
+title='public API'
+description='Description of the Kong public API used for developing and testing custom plugins'
+format='discount'
+file={
+ './kong/dao/',
+ './kong/tools/',
+ './spec/',
+}
+dir='doc'
+--readme='readme.md'
+sort=true
+sort_modules=true
+not_luadoc=true
+all=false
View
@@ -8,6 +8,8 @@
-- and is responsible for propagating clustering events related to data invalidation,
-- as well as foreign constraints when the underlying database does not support them
-- (as with Cassandra).
+-- @copyright Copyright 2016 Mashape Inc. All rights reserved.
+-- @license [Apache 2.0](https://opensource.org/licenses/Apache-2.0)
-- @module kong.dao
local Object = require "kong.vendor.classic"
@@ -1,7 +1,10 @@
--- Kong helper methods to send HTTP responses to clients.
-- Can be used in the proxy (core/resolver), plugins or Admin API.
-- Most used HTTP status codes and responses are implemented as helper methods.
---
+-- @copyright Copyright 2016 Mashape Inc. All rights reserved.
+-- @license [Apache 2.0](https://opensource.org/licenses/Apache-2.0)
+-- @module kong.tools.responses
+-- @usage
-- local responses = require "kong.tools.responses"
--
-- -- In an Admin API endpoint handler, or in one of the plugins' phases.
@@ -14,6 +17,7 @@
--
-- -- Raw send() helper:
-- return responses.send(418, "This is a teapot")
+
local cjson = require "cjson"
local meta = require "kong.meta"
@@ -1,6 +1,9 @@
---
--- Module for timestamp support.
+--- Module for timestamp support.
-- Based on the LuaTZ module.
+-- @copyright Copyright 2016 Mashape Inc. All rights reserved.
+-- @license [Apache 2.0](https://opensource.org/licenses/Apache-2.0)
+-- @module kong.tools.timestamp
+
local luatz = require "luatz"
local _M = {}
@@ -4,6 +4,9 @@
-- NOTE: Before implementing a function here, consider if it will be used in many places
-- across Kong. If not, a local function in the appropriate module is prefered.
--
+-- @copyright Copyright 2016 Mashape Inc. All rights reserved.
+-- @license [Apache 2.0](https://opensource.org/licenses/Apache-2.0)
+-- @module kong.tools.utils
local url = require "socket.url"
local uuid = require "resty.jit-uuid"
View
@@ -56,11 +56,14 @@ local function lookup(t, k)
end
--- Waits until a specific condition is met.
--- The check function will repeatedly be called (with a fixed interval), until the condition is met, or the
+-- The check function will repeatedly be called (with a fixed interval), until
+-- the condition is met, or the
-- timeout value is exceeded.
--- @param f check function that should return `thruthy` when the condition has been met
+-- @param f check function that should return `thruthy` when the condition has
+-- been met
-- @param timeout maximum time to wait after which an error is thrown
--- @return nothing. It returns when the condition is met, or throws an error when it times out.
+-- @return nothing. It returns when the condition is met, or throws an error
+-- when it times out.
-- @usage -- wait 10 seconds for a file "myfilename" to appear
-- helpers.wait_until(function() return file_exist("myfilename") end, 10)
local function wait_until(f, timeout)
@@ -82,6 +85,10 @@ local function wait_until(f, timeout)
end
end
+--- http_client.
+-- An http-client class to perform requests.
+-- @section http_client
+
--- Send a http request. Based on https://github.com/pintsized/lua-resty-http.
-- If `opts.body` is a table and "Content-Type" header contains `application/json`,
-- `www-form-urlencoded`, or `multipart/form-data`, then it will automatically encode the body
@@ -199,11 +206,14 @@ local function admin_client(timeout)
return http_client(conf.admin_ip, conf.admin_port, timeout)
end
---
+---
-- TCP/UDP server helpers
--
+-- @section servers
--- Starts a TCP server, accepting a single connection and then closes
+--- Starts a TCP server.
+-- Accepts a single connection and then closes, echoing what was received (single read).
+-- @name tcp_server
-- @param `port` The port where the server will be listening to
-- @return `thread` A thread object
local function tcp_server(port, ...)
@@ -227,7 +237,10 @@ local function tcp_server(port, ...)
return thread:start(...)
end
--- Starts a HTTP server, accepting a single connection and then closes
+--- Starts a HTTP server.
+-- Accepts a single connection and then closes. Sends a 200 ok, 'Connection: close' response.
+-- If the request received has path `/delay` then the response will be delayed by 2 seconds.
+-- @name http_server
-- @param `port` The port where the server will be listening to
-- @return `thread` A thread object
local function http_server(port, ...)
@@ -271,7 +284,9 @@ local function http_server(port, ...)
return thread:start(...)
end
--- Starts a UDP server, accepting a single connection and then closes
+--- Starts a UDP server.
+-- Accepts a single connection, reading once and then closes
+-- @name udp_server
-- @param `port` The port where the server will be listening to
-- @return `thread` A thread object
local function udp_server(port)
@@ -299,7 +314,9 @@ end
--------------------
-- Custom assertions
---------------------
+--
+-- @section assertions
+
local say = require "say"
local luassert = require "luassert.assert"
@@ -380,6 +397,8 @@ luassert:register("modifier", "request", modifier_request)
--- Generic fail assertion. A convenience function for debugging tests, always fails. It will output the
-- values it was called with as a table, with an `n` field to indicate the number of arguments received.
+-- @name fail
+-- @param ... any set of parameters to be displayed with the failure
-- @usage
-- assert.fail(some, value)
local function fail(state, args)
@@ -398,10 +417,11 @@ luassert:register("assertion", "fail", fail,
"assertion.fail.negative")
--- Assertion to check whether a value lives in an array.
+-- @name contains
-- @param expected The value to search for
-- @param array The array to search for the value
-- @param pattern (optional) If thruthy, then `expected` is matched as a string pattern
--- @returns the index at which the value was found
+-- @return the index at which the value was found
-- @usage
-- local arr = { "one", "three" }
-- local i = assert.contains("one", arr) --> passes; i == 1
@@ -503,7 +523,7 @@ luassert:register("assertion", "res_status", res_status, -- TODO: remove thi
-- @return the decoded json as a table
-- @usage
-- local res = assert(client:send { .. your request params here .. })
--- local body = assert.response(res).has.jsonbody()
+-- local json_table = assert.response(res).has.jsonbody()
local function jsonbody(state, args)
assert(args[1] == nil and kong_state.kong_request or kong_state.kong_response,
"the `jsonbody` assertion does not take parameters. "..
@@ -544,7 +564,7 @@ luassert:register("assertion", "jsonbody", jsonbody,
--- Adds an assertion to look for a named header in a `headers` subtable.
-- Header name comparison is done case-insensitive.
-- @name header
--- @param name header name to look for.
+-- @param name header name to look for (case insensitive).
-- @see response
-- @see request
-- @return value of the header
@@ -581,6 +601,8 @@ luassert:register("assertion", "header", res_header,
---
-- An assertion to look for a query parameter in a `queryString` subtable.
-- Parameter name comparison is done case-insensitive.
+-- @name queryparam
+-- @param name name of the query parameter to look up (case insensitive)
-- @return value of the parameter
local function req_query_param(state, args)
local param = args[1]
@@ -625,6 +647,8 @@ luassert:register("assertion", "queryparam", req_query_param,
-- Adds an assertion to look for a urlencoded form parameter in a mockbin request.
-- Parameter name comparison is done case-insensitive. Use the `request` modifier to set
-- the request to operate on.
+-- @name formparam
+-- @param name name of the form parameter to look up (case insensitive)
-- @return value of the parameter
local function req_form_param(state, args)
local param = args[1]
@@ -667,7 +691,13 @@ luassert:register("assertion", "formparam", req_form_param,
----------------
-- Shell helpers
-----------------
+-- @section Shell-helpers
+
+--- Execute a command.
+-- Modified version of `pl.utils.executeex()` so the output can directly be used on an assertion.
+-- @name execute
+-- @param ... see penlight documentation
+-- @return ok, stderr, stdout; stdout is only included when the result was ok
local function exec(...)
local ok, _, stdout, stderr = pl_utils.executeex(...)
if not ok then
@@ -676,6 +706,13 @@ local function exec(...)
return ok, stderr, stdout
end
+--- Execute a Kong command.
+-- @name kong_exec
+-- @param cmd Kong command to execute, eg. `start`, `stop`, etc.
+-- @param env (optional) table with kong parameters to set as environment
+-- variables, overriding the test config (each key will automatically be
+-- prefixed with `KONG_` and be converted to uppercase)
+-- @return same output as `exec`
local function kong_exec(cmd, env)
cmd = cmd or ""
env = env or {}
@@ -688,12 +725,22 @@ local function kong_exec(cmd, env)
return exec(env_vars.." "..BIN_PATH.." "..cmd)
end
+--- Prepare the Kong environment.
+-- creates the workdirectory and deletes any existing one.
+-- @param prefix (optional) path to the working directory, if omitted the test
+-- configuration will be used
+-- @name prepare_prefix
local function prepare_prefix(prefix)
prefix = prefix or conf.prefix
exec("rm -rf "..prefix.."/*")
return pl_dir.makepath(prefix)
end
+--- Cleans the Kong environment.
+-- Deletes the working directory if it exists.
+-- @param prefix (optional) path to the working directory, if omitted the test
+-- configuration will be used
+-- @name clean_prefix
local function clean_prefix(prefix)
prefix = prefix or conf.prefix
if pl_path.exists(prefix) then

0 comments on commit e3c1b3c

Please sign in to comment.