tobogganSe connecter

louise

The Louise language: compiler, runtime, std, tooling

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

253 lignes · 6236 octetsBrut · Historique
1/// Running another program to its end (ADR 0085).
2///
3/// let out = command.run (command.new "/usr/bin/pdftotext" ["in.pdf", "-"])
4///
5/// - **No shell.** The program gets exactly `args`: spaces, quotes, `$`
6/// and `;` reach it as they are.
7/// - **Nothing inherited.** Its environment is exactly `env`; a program
8/// named without a `/` is looked up in the `PATH` of `env` (absolute
9/// entries only), never in the caller's.
10/// - **Bounded.** Output past `max_stdout` or `max_stderr` is read and
11/// dropped (the run says it was cut). At `timeout_ms` the program and
12/// everything it started (its process group) get SIGTERM, and SIGKILL
13/// `grace_ms` later. When it ends, what is left of its group is killed.
14/// - **Never blocking.** The calling actor waits; the scheduler's threads
15/// do not. If the actor is killed, the program is killed and reaped.
16///
17/// A `Scratch` working directory is a fresh private directory: its inputs
18/// are written in first, the listed outputs are read back when the program
19/// ends (regular files only, at most `max_file` bytes each), and the
20/// directory is removed. A program that writes files thus needs no
21/// file-system access of the caller's.
22///
23/// `commands` is the same as an effect, for code that should be tested
24/// without running anything: `natively` runs for real, `scripted` answers
25/// from a function.
26
27import std/bytes
28import std/list
29
30/// Where a program runs.
31pub type Workdir
32{ /// The caller's working directory.
33 Inherit
34 /// This directory.
35, In(path: String)
36 /// A fresh private directory holding `inputs`; `outputs` are read back.
37, Scratch(inputs: List<(String, Bytes)>, outputs: List<String>, max_file: Int)
38}
39
40/// A program to run, with its arguments, environment and limits.
41pub type Command
42{ Command(
43 program: String
44 , args: List<String>
45 , env: List<(String, String)>
46 , workdir: Workdir
47 , stdin: Bytes
48 , max_stdout: Int
49 , max_stderr: Int
50 , timeout_ms: Int
51 , grace_ms: Int
52 )
53}
54
55/// `program` with `args`: no environment, the caller's directory, no
56/// input, 16 MiB of stdout and 64 KiB of stderr kept, 30 seconds, then
57/// 2 more after SIGTERM. Change a field with `Command(..cmd, env: …)`.
58pub fn new :: program: String args: List<String> -> Command
59{
60 Command( program
61 , args
62 , []
63 , Inherit
64 , bytes.empty ()
65 , 16777216
66 , 65536
67 , 30000
68 , 2000
69 )
70}
71
72/// How a program ended.
73@derive Eq Show Debug
74pub type Exit
75{ /// It exited with this status.
76 Exited(code: Int)
77 /// A signal ended it, not the timeout's.
78, Signalled(signal: Int)
79 /// The timeout passed: the last signal it was sent (SIGTERM is 15,
80 /// SIGKILL 9).
81, TimedOut(signal: Int)
82}
83
84/// A `Scratch` output, read back.
85pub type Collected
86{ Found(name: String, data: Bytes)
87 /// Past `max_file`: not read.
88, TooLarge(name: String, size: Int)
89 /// Not there, or not a regular file.
90, Absent(name: String)
91}
92
93/// A program's end and what it wrote.
94pub type Output
95{ Output(
96 exit: Exit
97 , stdout: Bytes
98 , stderr: Bytes
99 , stdout_cut: Bool
100 , stderr_cut: Bool
101 , files: List<Collected>
102 )
103}
104
105/// Why a program did not run.
106@derive Eq Show Debug
107pub type Error
108{ /// No such program (or working directory).
109 NotFound(String)
110 /// Not allowed to run it.
111, Denied(String)
112 /// A NUL byte, an environment name with `=`, a scratch name with a `/`,
113 /// a timeout that is not positive…
114, BadArgument(String)
115 /// Anything else the system refused.
116, Failed(String)
117}
118
119/// Runs `cmd` to its end.
120pub fn run :: cmd: Command -> Result<Output, Error> / <io>
121{
122 let ( kind
123 , dir
124 , inputs
125 , outputs
126 , max_file
127 ) = match cmd.workdir
128 { Inherit -> (0, "", [], [], 0)
129 , In(path) -> (1, path, [], [], 0)
130 , Scratch(inputs, outputs, max_file) -> (2, "", inputs, outputs, max_file)
131 }
132 let (names, values) = list.unzip cmd.env
133 let (in_names, in_data) = list.unzip inputs
134 let ran =
135 run_raw
136 cmd.program
137 cmd.args
138 names
139 values
140 kind
141 dir
142 in_names
143 in_data
144 outputs
145 max_file
146 cmd.stdin
147 cmd.max_stdout
148 cmd.max_stderr
149 cmd.timeout_ms
150 cmd.grace_ms
151 match ran
152 { Ok((exit, value, stdout, stderr, stdout_cut, stderr_cut, files)) ->
153 Ok( Output( ended exit value
154 , stdout
155 , stderr
156 , stdout_cut
157 , stderr_cut
158 , collected outputs files
159 )
160 )
161 , Error((code, message)) -> Error(refused code message)
162 }
163}
164
165/// Whether `out`'s program exited with status 0.
166pub fn succeeded :: out: Output -> Bool
167{
168 out.exit == Exited(0)
169}
170
171/// Running programs, as an effect.
172pub effect commands
173{
174 fn run_command :: cmd: Command -> Result<Output, Error>
175}
176
177/// Runs `action`, its programs run for real.
178pub fn natively :: action: fn() -> a / <commands, io | e> -> a / <io | e>
179{
180 handle
181 {
182 action ()
183 }
184 with
185 { run_command cmd -> run cmd }
186}
187
188/// Runs `action`, each of its programs answered by `answer` instead of
189/// run (for tests).
190pub fn scripted ::
191 answer: fn(Command) -> Result<Output, Error>
192 action: fn() -> a / <commands | e>
193 -> a / <e>
194{
195 handle
196 {
197 action ()
198 }
199 with
200 { run_command cmd -> answer cmd }
201}
202
203fn ended :: kind: Int value: Int -> Exit
204{
205 match kind { 0 -> Exited(value), 1 -> Signalled(value), _ -> TimedOut(value) }
206}
207
208fn refused :: code: Int message: String -> Error
209{
210 match code
211 { 0 -> NotFound(message)
212 , 1 -> Denied(message)
213 , 2 -> BadArgument(message)
214 , _ -> Failed(message)
215 }
216}
217
218fn collected ::
219 names: List<String>
220 files: List<(Int, Int, Bytes)>
221 -> List<Collected>
222{
223 list.map
224 (list.zip names files)
225 fn pair
226 {
227 let (name, (kind, size, data)) = pair
228 match kind
229 { 0 -> Found(name, data), 1 -> TooLarge(name, size), _ -> Absent(name) }
230 }
231}
232
233@extern c "tl_command_run"
234fn run_raw ::
235 program: String
236 args: List<String>
237 env_names: List<String>
238 env_values: List<String>
239 dir_kind: Int
240 dir: String
241 in_names: List<String>
242 in_data: List<Bytes>
243 out_names: List<String>
244 max_file: Int
245 stdin: Bytes
246 max_stdout: Int
247 max_stderr: Int
248 timeout_ms: Int
249 grace_ms: Int
250 -> Result<
251 (Int, Int, Bytes, Bytes, Bool, Bool, List<(Int, Int, Bytes)>)
252 , (Int, String)
253 > / <io>