Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 85 lines (58 sloc) 2.41 kb
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
1 # Parent-Child IPC in Jefe
2
3 Jefe and the child processes communicate through a pipe. Jefe sends a request,
4 the child handles the request, and the child returns a response to Jefe. Requests
5 and responses are JSON objects delimited by CRLF ("\r\n").
6
7 Requests include:
8
9b88230 @fictorial Updated docs
authored
9 * specifying untrusted scripts with an associated name ("compile")
10 * executing the scripts with an optional sandbox environment ("run")
11 * removing the untrusted scripts associated with a name ("remove")
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
12
9b88230 @fictorial Updated docs
authored
13 #### compile Request
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
14
15 The application sends the untrusted scripts to the child processes via Jefe.
9b88230 @fictorial Updated docs
authored
16 When the child receives the compile request, it creates a `Script` with the
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
17 given scripts. The child associates the `Script` with the given script name.
18 Reusing an existing name overwrites any current `Script` associated with the
19 given name.
20
21 Jefe sends:
22
9b88230 @fictorial Updated docs
authored
23 { "cmd":"compile"
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
24 , "scriptName":"$someName"
25 , "script":"$sourceCode"
26 } <CRLF>
27
9b88230 @fictorial Updated docs
authored
28 #### remove Request
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
29
30 The application no longer needs the given scripts. The child processes remove
31 the scripts by name.
32
33 Jefe sends:
34
9b88230 @fictorial Updated docs
authored
35 { "cmd":"remove"
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
36 , "scriptName":"$someName"
37 } <CRLF>
38
9b88230 @fictorial Updated docs
authored
39 #### run Request
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
40
9b88230 @fictorial Updated docs
authored
41 When the child receives the run request, it finds the `Script` by name,
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
42 and runs the script with the given sandbox object, and finally returns the
43 sandbox object as potentially modified by the scripts during the run.
44
45 Jefe sends:
46
9b88230 @fictorial Updated docs
authored
47 { "cmd":"run"
db89f6f @fictorial Split out IPC doc; added wordy circumference example; updated README
authored
48 , "scriptName":"$someName"
49 , "sandbox":{...}
50 } <CRLF>
51
52 When the scripts finishes running successfully, the (potentially updated) sandbox
53 object is returned to Jefe:
54
55 { "ok":true
56 , "response":{ "sandbox":{...} }
57 , "timeTaken":$elapsedMillis
58 } <CRLF>
59
60 When the scripts throws, the child responds with:
61
62 { "ok":true
63 , "response":{ "exception":{...} }
64 } <CRLF>
65
66 Note: `ok:true` denotes that the child was able to run the scripts, not that the
67 scripts ran without (its own definition of) error.
68
69 #### Sanity Checks
70
71 If Jefe somehow creates a malformed request (bug), the child prints to stderr and quits.
72
73 { "ok":false
74 , "reason":"malformed request"
75 } <CRLF>
76
77 Each child has a maximum input size for a sanity check. This is by default 5MiB.
78 Set the environment variable `JEFE_MAX_INPUT_SIZE` to alter this, or clone and update
79 the scripts. If a child receives too much data, it prints to stderr and quits.
80
81 { "ok":false
82 , "reason":"input too large
83 } <CRLF>
84
Something went wrong with that request. Please try again.