From 74aece56209ee534f89d11c0c8cee00e747359a3 Mon Sep 17 00:00:00 2001 From: pcarrier Date: Sat, 27 Nov 2010 16:48:16 +0000 Subject: [worker] initial spec git-svn-id: svn+ssh://svn.fedorahosted.org/svn/sos/trunk@1032 ef72aa8b-4018-0410-8976-d6e080ef94d8 --- worker/specs | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 worker/specs (limited to 'worker/specs') diff --git a/worker/specs b/worker/specs new file mode 100644 index 00000000..b709fde9 --- /dev/null +++ b/worker/specs @@ -0,0 +1,93 @@ +============== +gatherer specs +============== + +WORK IN PROGRESS + +When a command is expected, the line "#X#" is printed, where X is the number of +the request, starting a 0 and incremented after each processed request. + +Requests are spanned on multiple lines. The first line is the command, the +following lines are parameters (one parameter per line unless stated otherwise). + +Requests are all blocking. As they are read from stdin using readline(), +they can be buffered in stdin. + +When the number of parameters or returns is variable, it should be indicated +first. +When a parameter or returned value is not one line of printable characters, +its length as returned by len() should be indicated first. + +When gatherer is expected to write in a file, its parent directory should exist +and it will be opened with the "w" flag (unless stated otherwise). + +No timeout handling should be implemented in gatherer. +SIGTERM should be intercepted and: +- stop the current request and continue the normal flow of execution when a + request is being handled, +- be treated as an 'exit' request is a command was being read +- be treated as a 'reset' if a command was already read, but the request is + still being read. The current request should be dropped and a new request + should be read, the request counter is not incremented as no request was + processed. + +stderr is only used: +- by Python, for example to display exceptions. +- to print "ALIVE" when SIGUSR1 is received or after a "noop" request. + +Requests +-------- + +Command: "noop" +Params: +- None +Action: +- Prints "ALIVE" on stderr +Returns: +- Nothing + +Command: "exit" +Params: +- None +Action: +- The gatherer process returns 0 +Returns: +- Nothing + +Command: "glob" +Params: +- The globbing pattern +Action: +- Performs a glob.glob() +Returns: +- On the first line, a number of results, n +- On the following n lines, filenames, line by line + +Command: "exec" +Params: +- The command to send to a shell +Action: +- Executes the command in a shell using subprocess.Popen +Returns: +- On the first line, the return code +- On the second line, the length of its stdout output as return by len(), in + decimal. +- On the third line, the length of its stderr output as return by len(), in + decimal. +- Its stdout output, followed by a trailing '\n' +- Its stderr output, followed by a trailing '\n' + +Command: "exec2file" +Params: +- The command to send to a shell +- The filename to send the standard output to +Action: +- If the command is found, it is executed with this file as stdout and stderr. +Returns: +- The return code of the command in decimal. + +Command: "cp" +-- to be defined after staring at the current sosreport code. + +Command: "globcp" +-- to be defined after staring at the current sosreport code. -- cgit