Make a Func Binding - How you can interact with func-transmit

Func-Transmit

Func-transmit operates over standard-in/standard-out with data formatted with JSON or YAML (you can choose during invocation) and it's used to make func calls from another language easier than CLI calls. You can call func-transmit making information over stdin to invoke a func call on a specific minion and receiving response over stdout.



How you can invoke func-transmit

For your func-transmit invocation you need to decide whitch kind of supported parser/serializer you want to use. At the moment func-trasmit accepts only JSON or YAML messages and responds using the same dialect you have chosen during invocation. This decision was made taking care to serializers and their different language spread. YAML and JSON have both libraries packaged for many languages, so it should be easy to create a func binding using these parsers.

You can invoke func-transmit using a command like this:

func-transmit --json < data



--yaml instead of --json if you want to use YAML parser (could be also -j or -y for json or yaml)

Data must be send to func-transmit as standard input ('<' in CLI syntax) and could be a file or directly the "String" with all information Information expected during func-transmit invocation

You have to package your data to invoke func-transmit in a dictionary/map. Here the list of all parameters accepted.



  • clients: (Required) list of client you want to call. Could be list,single string or special character ("").
  • aysnc: (Optional-Default False) boolean that say if you want to call func in async mode (True) or in synch mode (False)
  • nforks: (Optional-Default 1) Number of forks you want to use to execute the calls to your clients. For example, if you have to execute a command on 10 different minions, you can use nforks=2 and each one call and get results on 5 minions.
  • module: (Required**) name of the module you want to call
  • method: (Required) method inside that module to invoke
  • parameters: (Optional-Default None) some additional parameters


** there are some specific "local" methods that, at the moment, do not need the module parameter (you can set what you want). But it's only to get information such as list_minions or something other local call.



Response returned

When func-transmit execution ends the response is packaged following the same structure of call. So you will receive a json/yaml message containing a dictionary with machinename and result.

{"host1": "result for your call", "host2":"result", ...}



The same structure is kept also if you call func-transmit with a single minion.



Async Calls

Asynchronous calls are an exception to what we have seen so far. In fact func-transmit responds to an invocation with a simple "String" containing the func process id (parsed with the selected dialect... but not really needed).

If you want to get results from a previous func-transmit call, you have to package a message containing:

 clients: ""

method: "job_status"

parameters: ["your process id"]



What you get as result of this call is a tuple with process_status and response packaged as "normal" func-transmit response:

[1, {host1:response, host2:response}]



Possible process statuses are:

0: your job is still running

1: finished

2: "lost in space". We cannot find job associated to provided pid

3: partial (executing but hasn't finished yet)

4: remote error