==============
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.
[test_incrementing_counter]
/Requests are spanned on multiple lines. The first line is the command, the
/following lines are parameters (one parameter per line unless stated otherwise).
[statement]
/Requests are all blocking. As they are read from stdin using readline(),
/they can be buffered in stdin.
[test_queuecommands]
/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.
[statement]
/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).
[statement]
/No timeout handling should be implemented in gatherer.
[statement]
SIGINT should be handled and:
- stop the current request, write INTERRUPTED to stderr then continue the normal
flow of execution when a request is being handled,
/- be treated as an 'exit' request is a command was being read
[test_ctrl_on_cmd_prompt_quits, test_ctrl_when_entering_command_quits]
/- 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.
[test_ctrlc_on_readparms_drops]
/stderr is only used:
/- by Python to display exceptions;
/- to print "ALIVE" when SIGUSR1 is received or after a "ping" request;
/- to print "UNKNOWN COMMAND" when a command is unknown;
/- to print "INTERRUPTED" when a command is interrupted with SIGINT.
[statement(easy to prove wrong, hard to prove right)]
Requests
--------
/Command: "noop"
/Params:
/- None
/Action:
/- None
/Returns:
/- Nothing
[test_basic_noop]
/Command: "ping"
/Params:
/- None
/Action:
/- Prints "ALIVE" on stderr
/Returns:
/- Nothing
[test_basic_ping NEED(stderr is being used)]
/Command: "exit"
/Params:
/- None
/Action:
/- The gatherer process returns 0
/Returns:
/- Nothing
[test_exit]
/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
[test_basic_glob, test_empty_glob]
Command: "exec"
Params:
- The command to send to a shell
Action:
- Executes the command in a shell using subprocess.Popen
Returns:
- The return code of the command
- The length of its stdout output as return by len(), in decimal.
- Its stdout output, followed by a trailing '\n'
- The length of its stderr output as return by len(), in decimal.
- Its stderr output, followed by a trailing '\n'
Command: "cp"
-- to be defined after staring at the current sosreport code.
Command: "globcp"
-- to be defined after staring at the current sosreport code.
