#  -*- text -*-
#
#
#  $Id: b5e15f7d496e8cda1123f1916834f81ba995b940 $

#######################################################################
#
#  = Ftp Module
#
#  The `ftp` module provides an xlat to retrieve files from FTP URIs.
#

#
#  == Configuration Settings
#
#  ftp { ... }::
#
ftp {
	#
	#  max_resp_size:: Maximum accepted response size
	#
	#  If the server returns responses larger than this they will be
	#  discarded.
#	max_resp_size = 16k

	#
	#  binary:: Should the response be treated as binary data
	#
	#  If this is `yes` then the output data will be octets. If it is
	#  `no` then the output data will be a string.
#	binary = no

	#
	#  connection { ... }:: Configure how connection handles are managed
	#  per thread.
	#
	connection {

		#
		#  Reusable connection handles are allocated in blocks. These
		#  parameters allow for tuning how that is done.
		#
		#  Since ftp requests are performed async, the settings here
		#  represent outstanding ftp requests per thread.
		#
		reuse {

			#
			#  min:: The minimum number of connection handles to keep
			#  allocated.
			#
			min = 10

			#
			#  max:: The maximum number of reusable connection handles to
			#  allocate.
			#
			#  Any requests to allocate a connection handle beyond this number
			#  will cause a temporary handle to be allocated. This is less
			#  efficient than the block allocation so `max` should be set to
			#  reflect the number of outstanding requests expected at peak
			#  load.
			max = 100

			#
			#  cleanup_interval:: How often to free un-used connection handles.
			#
			#  Every `cleanup_interval` a cleanup routine runs which will free
			#  any blocks of handles which are not in use, ensuring that at
			#  least `min` handles are kept.
			#
			cleanup_interval = 30s

		}

		#
		#  connect_timeout:: Connection timeout (in seconds).
		#
		#  The maximum amount of time to wait for a new connection to be
		#  established.
		#
		connect_timeout = 3.0
	}

}

#
#  == Expansions
#
#  The `rlm_ftp` module provides the following xlat function:
#
#  === %ftp.get(...)
#
#  Retrieve a file from an FTP URI
#
#  .Return: _string_ or _octets_
#
#  .Example
#
#  [source,unlang]
#  ----
#  auth-token := %ftp.get('ftp://example.com/auth.txt')
#  ----
#
