Network

Make external HTTP network requests and retrieve the results.

`cloud.network`

Network Requests

Heads Up!

All of the following methods are both getters and setters.

-- To get a value, omit any arguments
local host = network:host()

-- To set a an option
network:host('12.12.12.12')

-- Chain options
network:host('12.12.12.12'):port(8080)
local result, err = network:result()

Usage Example

JSON POST to host

local req = cloud.network.new('google.com') --host only, no path
req:path('/end/point')
req:method(cloud.POST)
req:body(<JSON CONTENT>)
req:headers({
  ['Content-Type'] = 'application/json',
  -- add more headers
})

local result, err = req:result()

New

.new

cloud.network.new( [host][, port] )

Parameters

Name	Description	Type	Default	Required
`host`	The hostname to connect to.	`string`	'127.0.0.1'	N
`port`	The port number to connect with.	`number`	80	N

The host and port can be set with the network instance methods as well.

Returns

A new network connection instance.

Example

local network = cloud.network.new('123.123.123.123', 8080)

Host

:host

network:host( hostname )

Parameters

Name	Description	Type	Default	Required
`hostname`	The hostname to connect to.	`string`	`nil`	Y

Returns

The hostname if no value is passed.

Example

local hostname = network:hostname()

--set
network:hostname('13.13.13.13')

Port

:port

network:port( port )

Parameters

Name	Description	Type	Default	Required
`port`	The port to connect to.	`number`	80	Y

Returns

The port if no value is passed.

Example

local port = network:port()

--set
network:port(8080)

Path

:path

network:path( path )

Parameters

Name	Description	Type	Default	Required
`path`	The path to connect to.	`string`	`nil`	Y

Returns

The path if no value is passed.

Example

local path = network:path()

--set
network:path('/echo/test')

:header

network:header( name, value )

Parameters

Name	Description	Type	Default	Required
`name`	The header name	`string`	`nil`	Y
`value`	The header value.	`string`	`nil`	Y

Returns

The header value if only the name key is passed.

Example

local header = network:header('Content-Type')

--set
network:header('Content-Type','application/json')

Headers

:headers

network:headers( headers )

Parameters

Name	Description	Type	Default	Required
`headers`	A table of request headers.	`table`	`nil`	N

Returns

All headers if no arguments are passed.

Example

local header = network:headers()

--set
network:headers({
  'Content-Type' = 'application/json',
  'Host' = '12.12.12.12.'
})

Heads Up!

The :headers method will clear all existing header assigments.

Method

:method

network:method( method )

Parameters

Name	Description	Type	Default	Required
`method`	A HTTP method. Can use `cloud` constants.	constant	`cloud.POST`	Y

Returns

The HTTP method name if no arguments are passed.

Example

local method = network:method()

--set
network:method(cloud.GET)

Timeout

:timeout

network:timeout( timeout )

Parameters

Name	Description	Type	Default	Required
`timeout`	Timeout in milliseconds.	`number`	500	Y

Returns

The HTTP method name if no arguments are passed.

Example

local timeout = network:timeout()

--set
network:timeout(30)

KeepAlive

:keep_alive

network:keep_alive( ka_ms, ka_pool )

Parameters

Name	Description	Type	Default	Required
`ka_ms`	`keep_alive` timeout in milliseconds.	`number`	30000	Y
`ka_pools`	`keep_alive` available pools.	`number`	5	Y

Returns

The HTTP method name if no arguments are passed.

Example

local keep_alive = network:keep_alive()

--set
network:keep_alive(30000, 20)

ChunkSize

:chunk_size

network:chunk_size( size )

Parameters

Name	Description	Type	Default	Required
`size`	The size of each data chunk.	`number`	8192	N

Returns

The chunk size value, if no arguments are passed.

Example

local chunk_size = network:chunk_size()

--set
network:chunk_size(1024)

SSLVerify

:ssl_verify

network:ssl_verify( verify_flag )

Parameters

Name	Description	Type	Default	Required
`verify_flag`	Enable or disable SSL verification.	`boolean`	`false`	N

Returns

The ssl_verify value, if no arguments are passed.

Example

local ssl_verify = network:ssl_verify()

--set
network:ssl_verify(true)

Body

:body

network:body( body_data )

Parameters

Name	Description	Type	Default	Required
`body_data`	Set or retrieve the request body.	`string`	`nil`	N

Returns

The body_data value, if no arguments are passed.

Example

local body_data = network:body()

--set
network:body("Here is some body data")

Result

:result

Compiles the instance options and makes the network request. Must be the last method called on a network request.

Heads Up!

network:result is a getter only.

network:result()

Parameters

None

Returns

The result if successful, otherwise nil and error message.

Example

local result, err = network:result()