aboutsummaryrefslogtreecommitdiffstats
path: root/worker/specs
blob: f6f22a1c9a6482da920eff4aa77330a561b1065f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
==============
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.