Remote control

Detroit engine supports remote function calls. This means that every function declared in Ano script can be called over the network. Remote function call is handy in automated testing and such, or programs can be daisy chained to control each other. Remote control support must not be disabled when running configure script (do not use --disable-remote), and remote control must be initialized in Ano script in order it to work.

Somewhere at the beginning of Ano script, call remote_init() function:

	remote_init

See examples/remote_control directory for live example.

When program to be remote controlled is started, it needs at least --auth_secret command line switch to be set, or secret can be set in config file. Auth secret is the secret string that remote controller must know when it is calling functions over the net. As an example, here is minimal Ano script which can be remote controlled:

;
; @ANO_SCRIPT_NAME		remote_control
; @ANO_SCRIPT_VERSION		0.0.2
; @ANO_SCRIPT_DESCRIPTION	Example how to run functions remotely
;
; @ANO_FLAGS_VAR_NAME_SUBS	[ ]
; @ANO_FLAGS_VAR_WARN_UNUSED	[ ]
;
; Copyright (c) 2016-2024, Jani Salonen <salojan@goto10.co>
; All rights reserved.
;

main {
	;
	; This is main program, just start remote thread and let it handle
	; remote connections. Program terminates when "remote_end" label is
	; called (see below) or <ctrl-c> is pressed.
	;

	remote_init
}

function remote_test [remote: allow] (param1, param2, param3) {
	;
	; To call this function remotely (set SECRET with -na switch):
	;
	;  $ telnet localhost 2109
	;    SECRET remote_test int:1 uint:2 float:3.3
	;
	; or by using remotetool:
	;
	;  $ echo 'remote_test 1 2 3' | ./engine/tools/remotetool -na SECRET
	;
	; End code returned to caller is the sum of params or -1 if error
	; occurs.
	;

	dump	param1
	dump	param2
	dump	param3

	end	(param1 + param2 + param3)
}

function remote_end [remote: allow] {
	;
	; To call this function remotely (set SECRET with -na switch):
	;
	; $ telnet localhost 2109
	;   SECRET remote_end
	;
	; or by using remotetool:
	;
	;  $ echo 'remote_end' | ./engine/tools/remotetool -na SECRET
	;
	; Exit code returned to caller is 123
	;

	exit	(123)
}

function remote_forbidden {
	;
	; This function cannot be run remotely, as there is no remote: allow
	; attribute.
	;
}

There is attributes available to use with Ano script functions to allow or deny to run them remotely:

remote attribute, which value can be one of:
1. deny, or
2. allow; they either forbids or permits function call remotely. Remote call is disabled by default and must be explicitly enabled for each function, so deny does not have any real practical effect.

;
; Procedure remote call can be enabled or disabled by using ANO_REMOTE_FUNCS
; tag, where each function or callback has either allow or deny keyword.
; Each function and keyword pair must be quoted. When using remote funcs tag,
; function remote attribute is not needed.
;
; @ANO_REMOTE_FUNCS	"remote_enabled = allow", \
;			"remote_forbidden = deny"
;

function remote_enabled [remote: allow] {
	; This function can be used remotely.
}

function remote_forbidden {
	; This function can not be used remotely as there is no allow
	; attribute.
}

function remote_forbidden [remote: deny] {
	; This function can not be used remotely.
}

Remote control can be done using telnet, or whatever client which is capable to send plain text to TCP socket. There is remotetool available in engine/tools directory which can be used for the job. It can be compiled by typing gmake remotetool in that directory. remotetool supports encrypted connections with GnuTLS or OpenSSL.

When not using supplied remotetool, the format of remote control string to send to program consists of at least two words separated by whitespace. First is the auth secret which must match to remote controlled program's --auth_secret string, and the second word is the function name to call. If function needs parameters, they are passed from third to n'th words. Numeral parameters may have type definition in front of them, separated by a colon. Needless to say, they must match what ever type of number function is expecting. In this example, the type of the parameters does not really matter.

To call remote_test function with three different type of numbers, pass program's remote control port something like:

SECRET remote_test int:1 uint:2 float:3.3

If remotetool is in use, just give function name and its parameters leaving out the secret, as remotetool takes care of sending the secret along with remote function call. Example:

$ remotetool -na SECRET -n6 -nh localhost -np 2109
  remote_test int:1 uint:2 float:3.3 <enter>
  remote_end <enter>

Alternatively, remote function call can be echoed to remotetool:

$ echo 'remote_end' | remotetool -na SECRET -n6 -nh localhost -np 2109

If remote function returns something, it will echo back to remote controller. List of supported number types are:

int8, or i8
int16, or i16
int32, or i32
int64, or i64
int128 or i128, might not be supported on every platform
isize

uint8, or u8
uint16, or u16
uint32, or u32
uint64, or u64
uint128 or u128, might not be supported on every platform
usize

char
short
int
long

uchar
ushort
uint
ulong

float, or f32
double, or f64