diff options
Diffstat (limited to 'lambda-calcul/rust/static')
| -rw-r--r-- | lambda-calcul/rust/static/README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/lambda-calcul/rust/static/README.md b/lambda-calcul/rust/static/README.md new file mode 100644 index 0000000..08dfc3d --- /dev/null +++ b/lambda-calcul/rust/static/README.md @@ -0,0 +1,88 @@ +# Rust λ-calcul reference implementation + +This directory contains a reference implementation of a normal order semantics λ-calculus based language. +Current syntax is based on S-expressions, ie. Lisp. There is a command-line interpreter for batch and interactive evaluation of input, and an embryonic tester daemon. + +# Tester + +The tester daemon is inspired by [Extreme Startup](https://github.com/rchatley/extreme_startup): It's a REST-ish server and client that allows to repeatedly send λ-terms to a remote execution engine and compare the result against its expectations. + +The overall interaction flow is the following: + +* HTTP server starts on some known port (eg. 8080) +* Clients register themselves with the server +* Server registers client and starts sending expressions to evaluate +* Leaderboard is updated depending on whether clients' answers are correct or not + +## Detailed Interactions + +We use the following variables to represent, well, variable elements that should be replaced depending on the actual deployment: + +* `SERVER_BASE_URL`: the base URL of the server, should be communicated by facilitator in some ways, eg. `http://1.2.3.4:8080`, +* `CLIENT_URL`: URL of a client as defined by their specific implementation. + +### Registration + +The client needs to send a `POST /register` request, passing in as payload a JSON object with a `url` and `name` string fields: + +``` +curl -v -X POST -d '{"url":"${CLIENT_URL}", "name": "toto", "encoding": "Json"}' -H 'Content-type: application/json' ${SERVER_BASE_URL}/register +``` + +The payload is expected to be a JSON object with the following fields: +* `url`: The client URL for the server to callback and send expressions to evaluate +* `name`: The name of this client +* _(Optional)_ `encoding`: Which encoding to use to receive expressions and send responses. One of `Json` or `Sexp`, defaulting to `Json`. + +Notes: + +* Obviously, client needs to start a HTTP server able to respond to a `GET` request at the given URL. To check or troubleshoot connectivity, one can use the [netcat](https://linux.die.net/man/1/nc) program to fire up a local server with `nc -l 12345` and use the ip and port to register the client. This will echo in the terminal whatever the _server_ sends +* If URL is not already registered, server accepts the registration (returning a `200 OK` result) and starts a _testing thread_ + +* The _tester_ then repeatedly sends `POST` requests to the client's registered URL + * The body of the request is plain text S-expression representing a λ-term + * The tester expects the response to be the plain text result of the evaluation of those terms +* If the client fails to answer, or answers wrongly, the server keeps sending the same request +* If the client's answer is correct, the server sends another term to evaluate and awards 1 point to the client +* The `/leaderboard` endpoint provides a crude HTML page listing each clients' current score + +## Building + +This software is written in Rust (sorry @xvdw), so one needs a Rust toolchain installed, then: + +``` +cargo build && cargo test +``` + +## Running + +To run the server: + +``` +cargo run --bin server +``` + +There are `--port` and `--host` arguments should one want to change the default `127.0.0.1:8080` + +# NOTES + +* [x] make command line to register more explicit +* [x] `nc -l` is a simple echo server to show what's sent by the server +* [x] keep the readme exposed by the server +* [ ] use JSON formatting for request/response +* [ ] debug user address on the leaderboard page + * [ ] shows status of client (not connected/connected/replying correctly or not) +* [ ] add more logs to server to help troubleshoot users access/registration +* [ ] THE SERVER MUST NOT CRASH +* [ ] cheatsheet λ-calcul exposed on `/help` +* [ ] propose to send JSON or S-Exp +* [ ] persist user state to avoid losing connections +* [ ] deploy automatically server on punkachien.net with radicle CI +* [ ] better JSON representation for AST than raw serde stuff +* [ ] Document JSON format... + +* [ ] ask people to implement something +* [ ] prepare starter kit to overcome +* [ ] différentes couleurs de pistes (verte/rouge/noire) +* [ ] pair programming w/ Manu, people do their own stuff if they want +* [ ] ne pas oublier le routeur wifi |