Luchia

• Index

Contents

• Local Functions
• Methods

Classes

• luchia.core.attachment
• luchia.core.document
• luchia.core.log
• luchia.core.server
• luchia.database
• luchia.document
• luchia.utilities

Modules

• luchia
• luchia.conf

Topics

• INTRODUCTION

Examples

• core.attachment.lua
• core.document.lua
• core.log.lua
• core.server.lua
• database.lua
• document.lua
• luchia.lua
• utilities.lua

Class luchia.core.server

Core server handler class.

Note that for most cases, the methods in the higher-level luchia.database, luchia.document, and luchia.utilities modules should be used; this module provides the core server functionality that those higher-level modules use, but can be used directly for more complex server requests.

See the core.server.lua example for more detail.

Info:

• Copyright: 2011-2015 Chad Phillips
• Author: Chad Phillips

Local Functions

luchia.core.server.valid_protocol(server)	Checks for a valid server protocol.
luchia.core.server.valid_host(server)	Checks for a valid server host.
luchia.core.server.valid_port(server)	Checks for a valid server port.

Methods

luchia.core.server:new(self, params)	Creates a new core server handler.
luchia.core.server:request(params)	Send a request to the CouchDB server.
luchia.core.server:prepare_request(params)	Prepare a request to the CouchDB server.
luchia.core.server:prepare_request_data()	Prepare request data before sending it to the server.
luchia.core.server:execute_request()	Execute a request to the CouchDB server.
luchia.core.server:parse_response_data(data)	Parse the response data from the CouchDB server if necessary.
luchia.core.server:parse_json(json_string)	Parse a JSON string.
luchia.core.server:http_request()	Make an HTTP request to the server.
luchia.core.server:build_url()	Builds a URL based on the server connection object, the request path, and the request parameters.
luchia.core.server:stringify_parameters(params)	Builds a query string from a Lua table of query parameters.
luchia.core.server:uuids(count)	Retrieve uuids from the CouchDB server.
luchia.core.server:response_ok(response)	Check the response for success.

Local Functions

Methods

luchia.core.server.valid_protocol(server)

Checks for a valid server protocol.

Parameters:

• server

Returns:

true on a valid protocol, nil otherwise.

Usage:

valid_protocol(server)

luchia.core.server.valid_host(server)

Checks for a valid server host.

NOTE: This regex is a best effort to follow the hostname specification in

   RFC 1123, but it's not perfect: some labels beginning and ending with
   a dash are allowed through, but are not permitted by the RFC.

Parameters:

• server

Returns:

true on a valid host, nil otherwise.

Usage:

valid_host(server)

luchia.core.server.valid_port(server)

Checks for a valid server port.

Parameters:

• server

Returns:

true on a valid port, nil otherwise.

Usage:

valid_port(server)

Methods

luchia.core.server:new(self, params)

Creates a new core server handler.

In order to talk to CouchDB, a server object must be created with the proper connection parameters.

Parameters:

• self
• params Optional. A table with the metadata necessary to create a new server object. If a needed connection parameter is not passed here, the default server setting configuration will be used instead to build the server object.
  • protocol The protocol to use, currently only "http" is allowed.
  • host The host name, eg. "localhost" or "www.example.com".
  • port The port to use, eg. "5984".
  • user For authentication scenarios, the user to authenticate as.
  • password For authentication scenarios, the user's password.
  • custom_request_function A custom request function can be substituted for the default http.request function available from luasocket. The testing framework uses this to mock for unit tests.
  • custom_configuration A custom configuration table can be substituted for the default one available from luchia.conf. The testing framework uses this to mock for unit tests.

Returns:

A new server object.

Usage:

srv = luchia.core.server:new(params)

luchia.core.server:request(params)

Send a request to the CouchDB server.

In order to talk to CouchDB, a server object must be created with the proper connection parameters.

Parameters:

• params Optional. A table with the request metadata.
  • method Optional. The server method, must be one of "GET", "POST", "PUT", "DELETE", "HEAD", "COPY". Default is "GET".
  • path Optional. The path on the server to access.
  • query_parameters Optional. A table of query parameters to pass to the server, key is parameter name, value is parameter value, eg. '{ include_docs = "true", limit = "3" }'.
  • headers Optional. A table of headers to pass to the server, eg. '{ destination = "doc_id" }'.
  • parse_json_response Optional. Boolean. Set to false to disable automatic parsing of the JSON response from the server into a Lua table. Default is true.
  • data Optional. A data object containing data to pass to the server.

Returns:

The following four values, in this order: responsedata, responsecode, headers, status_code.

See also:

• prepare_request
• prepare_request_data
• execute_request

Usage:

response_data, response_code, headers, status_code =
   srv:request(params)

luchia.core.server:prepare_request(params)

Prepare a request to the CouchDB server.

This method is invoked by the request method to set up the necessary parameters before making a request to the CouchDB server. It should not generally need to be called separately.

Parameters:

• params Optional. A table with the request metadata.

See also:

request

Usage:

srv:prepare_request(params)

luchia.core.server:prepare_request_data()

Prepare request data before sending it to the server.

The server object calls this method prior to sending a request to the server. If a data object has been passed to the server, and it implements the 'preparerequestdata' method, it will be called and passed the entire server object, so that it may make any necessary adjustments prior to the request. In particular it should properly set the 'requestdata' and 'contenttype' attributes on the server object to appropriate values for the data being sent.

Note that the core document and attachment classes already implement this method, so it should generally not need to be implemented.

See also:

request

luchia.core.server:execute_request()

Execute a request to the CouchDB server.

This method is invoked by the request method to send a request to the CouchDB server, then collect and parse the response. It should not generally need to be called separately.

Returns:

The following four values, in this order: responsedata, responsecode, headers, status_code.

See also:

• request
• http_request
• parse_response_data

Usage:

response_data, response_code, headers, status_code =
   srv:execute_request()

luchia.core.server:parse_response_data(data)

Parse the response data from the CouchDB server if necessary.

Parameters:

• data Required. The data to parse.

Returns:

The parsed data.

See also:

• execute_request
• parse_json

Usage:

parsed_data = srv:parse_response_data(data)

luchia.core.server:parse_json(json_string)

Parse a JSON string.

Parameters:

• json_string Required. The JSON string to parse.

Returns:

The parsed JSON string, converted to a Lua table.

See also:

parse_response_data

Usage:

srv:parse_json('{"key": "value"}')

luchia.core.server:http_request()

Make an HTTP request to the server.

This is the low level method to make a server request, and should generally not be used.

Returns:

The following four values, in this order: responsedata, responsecode, headers, status_code.

See also:

• execute_request
• build_url

Usage:

response_data, response_code, headers, status_code =
   srv:http_request()

luchia.core.server:build_url()

Builds a URL based on the server connection object, the request path, and the request parameters.

Returns:

A URL string.

See also:

• http_request
• stringify_parameters

luchia.core.server:stringify_parameters(params)

Builds a query string from a Lua table of query parameters.

Parameters:

• params Optional. A table of query parameters, key is parameter name, value is parameter value. If not provided, the query_parameters attribute on the server object is used.

Returns:

The query string.

See also:

build_url

Usage:

srv:stringify_parameters({ include_docs = "true", limit = "3" })

luchia.core.server:uuids(count)

Retrieve uuids from the CouchDB server.

This provides a convenient way to get random unique identifiers from the server itself if no other facility is available to generate them.

Parameters:

• count Optional. The number of uuids to generate, default is 1.

Returns:

A list of uuids.

Usage:

srv:uuids(10)

luchia.core.server:response_ok(response)

Check the response for success.

A convenience method to ensure a successful request.

Parameters:

• response Required. The response object returned from the server request.

Returns:

true if the server responsed with an ok:true, false otherwise.

Usage:

operation_succeeded = srv:response_ok(response)