fix: clarify registration and use of netcat

1 files changed, 42 insertions, 24 deletions

diff --git a/lambda-calcul/rust/README.md b/lambda-calcul/rust/README.md
index f4bced5..e3a9e60 100644
--- a/lambda-calcul/rust/README.md
+++ b/lambda-calcul/rust/README.md
@@ -7,15 +7,33 @@ Current syntax is based on S-expressions, ie. Lisp. There is a command-line inte
 
 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 interaction flow is simple:
+The overall interaction flow is the following:
 
 * HTTP server starts on some known port (eg. 8080)
-* Client sends a `POST /register` request, passing in as payload a JSON object with a `url` and `name` string fields
-  ```
-  curl -v -X POST -d '{"url":"http://127.0.0.1:8888/eval", "name": "toto"}' -H 'Content-type: application/json' http://localhost:8080/register
-  ```
-* Obviously, client needs to start a HTTP server able to respond to a `GET` request at the given URL
-* If URL is not already registered, server accepts the registration (returning a 200 result) and starts a _testing thread_
+* 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"}' -H 'Content-type: application/json' ${SERVER_BASE_URL}/register
+```
+
+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
@@ -43,20 +61,20 @@ There are `--port` and `--host` arguments should one want to change the default
 
 # NOTES
 
-* make command line to register more explicit
-* `nc -l` is a simple echo server to show what's sent by the server
-* 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
-
-* 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
+* [x] make command line to register more explicit
+* [x] `nc -l` is a simple echo server to show what's sent by the server
+* [ ] 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
+
+* [ ] 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