Anatomy of a service - ralfw/csfe GitHub Wiki

A CSFE service is a program without a user interface. It's started from the command line, can be customised with command line parameters, but mainly takes its input from files and writes its results to files.

All files necessary to run a service need to be put into the service directory (or be accessible globally), e.g.

/split
  split.exe
  some_useful_lib.dll
  ...

The service will be run in its directory; it will be the current directory during execution.

Reading input, writing output

Input and output for services is done with files. Input files are passed to the service in its local /input directory, output files must be written to its local /output directory.

/split
  split.exe
  some_useful_lib.dll
  ...
  /input
  /output

These directories are created automatically by the CSFE if they are not present.

When a service is called it should process all input files and produce all output files necessary. But it does not need to care about where the input files are coming from or where the output files are going to.

If a service is stateful across calls/input files, then it needs to take care of its persistence needs itself. Such data should be kept separate from the input/output directories.

Input files processed successfully should be deleted by the service so as to not be processed again the next time it's run. Output files written will be out of the output directory by the CEFE. The process can assume the output directory to be empty when started.

In case no output files are produced by a service a subsequent service will not be run, because there is no data to be processed.

A service should not assume input files to have any specific names. Nor should it produce output files where names have specific meaning. Exception: a service with several different output ports can tag its output files with the name of the port the data is flowing out from, e.g. "12344-portA". A subsequent switch operation then can react on such tags.

Even though output files should have no special names they should be named in a manner so they can be sorted chronologically - at least if several files are produced per execution. Then the CSFE will process them in the order they were created.

How the input/output files are structured is of no concern to the CSFE. That's a matter of the contracts between the services and their environment.

Service definition

Each service needs to be accompanied by a service definition file called service.json:

/split
  service.json
  split.exe
  some_useful_lib.dll
  ...
  /input
  /output

The service definition contains some meta-data to be collected by the CSFE service crawler before it compiles a flow description.

The service definition's structure is small and simple:

{
  "name":"split",
  "executable":"mono",
  "arguments": "split.exe"
}

• name: Name of service to be used in flow descriptions. If the name is missing the name of the service directory is assumed.
• executable: The name of the file to be run by the CSFE. It can be the service program's name itself or - as in the above case - a runtime to use. When starting the service with this command the current directory is the service directory. Use %path in this string as a placeholder for the service directory. This will be necessary if the executable is located in the service directory (e.g. a Go program) instead of being globally available (e.g. a runtime like mono or ruby).
• arguments: Any data to pass to the executable on the command line. Use %argument in this string if the service should be parameterised by the operation in the flow description.