Module middleware

APItools Middleware

Middleware documentation of APItools.

All this should be available when middleware is evaluated.

Check out our GitHub Repository and Middleware repository.

If you don't have enough, we have a blog and a documentation.

Info:

  • Copyright: APItools 2014
  • License: MIT

Bucket

bucket.middleware Middleware Bucket Every middleware has own bucket.
bucket.service Service Bucket Every service has own bucket.

Console

console Console for all the available methods.

HTTP

http HTTP Client Check http.get for details.

Functions

metric.count (metric[, increment=1]) store integer values as simple count
metric.set (metric, value) store integer values as set then you can get avg,p99 and other statistic
base64.decode (str) Decodes the str argument as a base64 digest to the raw form.
base64.encode (str) Encode str to a base64 digest.
send.email (to, subject, msg) Send email
send.event (event) Create Event
send.notification (event) Create middleware notification Creates Event and will be overriden to middleware channel.
time.seconds () Current time in seconds Returns the elapsed seconds from the epoch.
time.http (sec) Formats number of seconds to a HTTP-date string Returns a formated string in "HTTP-date" format specified by the RFC 7231.
time.now () Returns a floating-point number for the elapsed time in seconds (including milliseconds as the decimal part) from the epoch for the current time stamp.
json.encode (object) JSON Encode table to a JSON string.
json.decode (string) Decode JSON string to an object.
hmac.sha256 (str, key) Create keyed-hash message authentication code using HMAC-SHA-256.

Tables

trace Trace object of current request.

Class Trace

Trace.req Current HTTP Request like it will be stored and displayed in the UI.
Trace.res Will contain the response like it will be stored (once it is processed).
Trace.total_time time in seconds how long it took APItools to return the request
Trace.service_id id of the service that processed the request
Trace.starred starred

Class Event

event.channel channel required attribute, can be for example middleware, email, stats, ...
event.level level one of the {'log', 'debug', 'info', 'warn', 'error' }
event.msg msg required attribute, a message of the event

Class HTTP

http.get (url, options) Make GET request.
http.head (url, options) Make HEAD request.
http.delete (url, options) Make DELETE request.
http.options (url, options) Make OPTIONS request.
http.put (url, body, options) Make PUT request.
http.post (url, body, options) Make POST request.
http.patch (url, body, options) Make PATCH request.
HTTP.urlencoded Urlencoded serializer Serializes your data to application/x-www-form-urlencoded format and sets correct Content-Type header.
HTTP.json JSON serializer Converts the body to JSON unless it is already a string and sets correct Content-Type application/json.
HTTP.response Response returned by http.get and similar calls
HTTP.options Options that can be passed to http calls.

Class Console

console.log (...) log
console.debug (...) debug
console.info (...) info
console.warn (...) warn
console.error (...) error

Class Rack

Rack.Response Response
Rack:next_middleware () evaluates other middlewares and returns a response
Rack:middleware (request, next_middleware) executing a middleware
Rack.Request Request

Class Bucket

Bucket.get (field_name) get a value
Bucket.set (field_name, value, exptime) set a value
Bucket.delete (field_name) delete a value
Bucket.incr (field_name[, amount=1]) increment a value
Bucket.add (field_name, value, exptime) set the value if it does not exist
Bucket.delete_all () delete all values
Bucket.get_keys () get all keys


Bucket

bucket.middleware
Middleware Bucket Every middleware has own bucket. You can access it by using methods of Bucket methods as bucket.middleware.

See also:

Usage:

    local cached = bucket.middleware.get('my-cached-value')
bucket.service
Service Bucket Every service has own bucket. All middlewares can access it by using Bucket methods as bucket.service.

See also:

Usage:

    local cached = bucket.service.get('my-cached-value')

Console

console
Console for all the available methods. Almost like in the browser.

HTTP

http
HTTP Client Check http.get for details.

See also:

Functions

metric.count (metric[, increment=1])
store integer values as simple count

Parameters:

  • metric string name
  • increment int (default 1)
metric.set (metric, value)
store integer values as set then you can get avg,p99 and other statistic

Parameters:

  • metric string name
  • value number
base64.decode (str)
Decodes the str argument as a base64 digest to the raw form. Returns nil if str is not well formed.

Parameters:

  • str string base64 encoded string

Returns:

    optional string decoded string
base64.encode (str)
Encode str to a base64 digest.

Parameters:

Returns:

    string base64 encoded string
send.email (to, subject, msg)
Send email

Parameters:

  • to string email address of the receiver
  • subject string email subject
  • msg string the email body
send.event (event)
Create Event

Parameters:

  • event table the event to be created
send.notification (event)
Create middleware notification Creates Event and will be overriden to middleware channel.

Parameters:

  • event table the event to be created
time.seconds ()
Current time in seconds Returns the elapsed seconds from the epoch.

Returns:

    int elapsed seconds from the epoch
time.http (sec)
Formats number of seconds to a HTTP-date string Returns a formated string in "HTTP-date" format specified by the RFC 7231. It is used for example in Last-Modified header and looks like "Tue, 15 Nov 2014 08:12:31 GMT".

Parameters:

  • sec int timestamp in seconds (like those returned from time.seconds)

Returns:

    string HTTP-date formatted string
time.now ()
Returns a floating-point number for the elapsed time in seconds (including milliseconds as the decimal part) from the epoch for the current time stamp.

Returns:

    float elapsed seconds from the epoch (including miliseconds)
json.encode (object)
JSON Encode table to a JSON string.

Parameters:

  • object table to be serialized

Returns:

    string JSON string
json.decode (string)
Decode JSON string to an object.

Parameters:

  • string string to be deserialized

Returns:

    table deserialized object
hmac.sha256 (str, key)
Create keyed-hash message authentication code using HMAC-SHA-256.

Parameters:

Returns:

    string digest

Tables

trace
Trace object of current request. After all the middleware finish, it will be persisted for later search.

See also:

Usage:

  • trace.my_middleware = 'some metadata'
  • trace.res.processed = true

Class Trace

Trace
Trace.req
Current HTTP Request like it will be stored and displayed in the UI.

Fields:

  • query string query string
  • headers table
  • uri_full string whole URI including scheme, host, port, path and query string
  • uri_relative string path + query string
  • args table parsed query string
  • method string HTTP Method
  • scheme string HTTP Scheme (http/https)
  • uri string just the path
  • host string value of Host header
Trace.res
Will contain the response like it will be stored (once it is processed).

Fields:

Trace.total_time
time in seconds how long it took APItools to return the request
  • total_time number
Trace.service_id
id of the service that processed the request
  • service_id number
Trace.starred
starred
  • starred boolean

Class Event

Event
event.channel
channel required attribute, can be for example middleware, email, stats, ...
event.level
level one of the {'log', 'debug', 'info', 'warn', 'error' }
event.msg
msg required attribute, a message of the event

Class HTTP

HTTP
http.get (url, options)
Make GET request.

Parameters:

Returns:

    response a response
http.head (url, options)
Make HEAD request.

Parameters:

Returns:

    response a response
http.delete (url, options)
Make DELETE request.

Parameters:

Returns:

    response a response
http.options (url, options)
Make OPTIONS request.

Parameters:

Returns:

    response a response
http.put (url, body, options)
Make PUT request. The body is serialized by HTTP.urlencoded unless you used different serializer.

Parameters:

Returns:

    response a response
http.post (url, body, options)
Make POST request. The body is serialized by HTTP.urlencoded unless you used different serializer.

Parameters:

Returns:

    response a response
http.patch (url, body, options)
Make PATCH request. The body is serialized by HTTP.urlencoded unless you used different serializer.

Parameters:

Returns:

    response a response
HTTP.urlencoded
Urlencoded serializer Serializes your data to application/x-www-form-urlencoded format and sets correct Content-Type header.

Usage:

    http.urlencoded.post(url, { example = 'table' })
HTTP.json
JSON serializer Converts the body to JSON unless it is already a string and sets correct Content-Type application/json.

See also:

Usage:

    http.json.post(url, { example = 'table' })
HTTP.response
Response returned by http.get and similar calls

Fields:

  • status int HTTP Status Code
  • headers table HTTP Headers
  • body string response body
  • ok bool
HTTP.options
Options that can be passed to http calls.

Fields:

  • headers table table of HTTP headers
  • ssl table table with ssl options

Usage:

  • http.get(uri, { ssl = { verify = false }})
  • http.get(uri, { headers = { my_header = 'value' }})

Class Console

Console
console.log (...)
log

Parameters:

  • ... objects to be printed
console.debug (...)
debug

Parameters:

  • ... objects to be printed
console.info (...)
info

Parameters:

  • ... objects to be printed
console.warn (...)
warn

Parameters:

  • ... objects to be printed
console.error (...)
error

Parameters:

  • ... objects to be printed

Class Rack

Rack
Rack.Response
Response

Fields:

Rack:next_middleware ()
evaluates other middlewares and returns a response

Returns:

    Rack.Response
Rack:middleware (request, next_middleware)
executing a middleware

Parameters:

Rack.Request
Request

Fields:

Usage:

     return function(request, next_middleware)
   request.uri = '/different'
   return next_middleware()
 end

Class Bucket

Bucket
Bucket.get (field_name)
get a value

Parameters:

Returns:

    value previously stored

Usage:

  • local response = bucket.middleware.get('cached-response'')
  • local val = bucket.service.get(key)
Bucket.set (field_name, value, exptime)
set a value

Parameters:

  • field_name string key name
  • value boolean, number, string or nil a value to be stored
  • exptime int time to expire in seconds

Returns:

  1. bool indicates whether the key-value pair is stored or not
  2. optional string error message, can be "no memory"
  3. bool indicates whether other valid items have been removed forcibly when out of storage in the shared memory zone

Usage:

  • local ok, err = bucket.middleware.set('cached-api-key', 'secret-api-key', 3600)
  • bucket.middleware.set('cached-response', response, 60)
Bucket.delete (field_name)
delete a value

Parameters:

Usage:

  • bucket.middleware.delete(key)
  • bucket.service.delete(key)
Bucket.incr (field_name[, amount=1])
increment a value

Parameters:

  • field_name string a key
  • amount number amount to increment/decrement (default 1)

Returns:

    number new value

Or

  1. nil
  2. string not found

Or

  1. nil
  2. string not a number

Usage:

  • bucket.middleware.incr('hits') -- default is 1
  • bucket.middleware.incr('downloaded-kb', 3500)
Bucket.add (field_name, value, exptime)
set the value if it does not exist

Parameters:

  • field_name string a key
  • value boolean, number, string or nil a value to be stored
  • exptime int expire time in seconds

Returns:

  1. bool indicates whether the key-value pair is stored or not
  2. optional string error message, can be "no memory"
  3. bool indicates whether other valid items have been removed forcibly when out of storage in the shared memory zone

Usage:

    if bucket.middleware.add('first-call', true) then response.body = 'you won!' end
Bucket.delete_all ()
delete all values
Bucket.get_keys ()
get all keys

Returns:

    {string, ...} all keys
generated by LDoc 1.4.3 Last updated 2014-12-03 13:05:48