From 9652978433b3a327573ddbfc51c23070869e0c9c Mon Sep 17 00:00:00 2001
From: Quentin Dufour <quentin@deuxfleurs.fr>
Date: Thu, 15 Sep 2022 17:12:21 +0200
Subject: Improve README

---
 README.md                   | 26 +++++++++++++++++++++++---
 scenarios/fragments/warp.py |  0
 scenarios/garage-warp       |  7 +++++++
 topo/50ms.yml               | 34 ++++++++++++++++++++++++++++++++++
 topo/single-dc.yml          | 34 ----------------------------------
 5 files changed, 64 insertions(+), 37 deletions(-)
 create mode 100644 scenarios/fragments/warp.py
 create mode 100755 scenarios/garage-warp
 create mode 100644 topo/50ms.yml
 delete mode 100644 topo/single-dc.yml

diff --git a/README.md b/README.md
index 8b23bce..2259901 100644
--- a/README.md
+++ b/README.md
@@ -42,14 +42,34 @@ You can check that everything has been installed by running in a python REPL:
 import garage_admin_sdk
 ```
 
-## Run a test
+## Topologies
 
-(Not yet implemented)
+All topologies:
+  - `./topo/with-vdsl.yml` - A topology mixing datacenters with fast internal connectivity and an isolated VDSL node
+  - `./topo/50ms.yml` - An artifical topology simulating nodes with high bandwidth but with a fixed 50ms latency, useful to quantify the impact of latency on a distributed software
+  - `./topo/multi-dc.yml` - Simulate 3 DC interconnected with 50ms latency WAN network and close to zero latency inside the DC
+  - `./topo/slow.yml` - Simulate 3 nodes interconnected with a low latency, very low bandwidth link. Useful to debug bandwidth bottlenecks
+
+Feel free to write new topologies!
+
+## Scenarios
+
+All scenarions:
+ - `./scenarios/garage-s3lat` - Run s3lat on Garage
+ - `./scenarios/garage-warp [default|fast]` - Run warp on Garage. 2 flavors are available: fast and default.
+
+How to run them:
 
 ```bash
-./mknet scenario ./topo/single-dc.yml ./scenarios/garage-s3lat
+./mknet scenario <topology> <scenario>
+./mknet scenario ./topo/50ms.yml ./scenarios/garage-s3lat
 ```
 
+How to write good scenarios:
+  - If a scenario can be run with multiple different parameters, write one scenario with multiple flavors
+  - If the logic ran is different, write a new scenario
+  - A scenario code must remain short and looks like a DSL, abstract the logic in the `fragments/` module
+
 ## Manual usage
 
 ```bash
diff --git a/scenarios/fragments/warp.py b/scenarios/fragments/warp.py
new file mode 100644
index 0000000..e69de29
diff --git a/scenarios/garage-warp b/scenarios/garage-warp
new file mode 100755
index 0000000..e8d466a
--- /dev/null
+++ b/scenarios/garage-warp
@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+from fragments import garage, warp, shared
+
+if shared.id() == 1:
+  pass
+
+
diff --git a/topo/50ms.yml b/topo/50ms.yml
new file mode 100644
index 0000000..39427aa
--- /dev/null
+++ b/topo/50ms.yml
@@ -0,0 +1,34 @@
+links:
+  - &fiber
+    bandwidth: 100M
+    latency: 50ms
+    jitter: 10ms
+
+zones:
+  - &dc1
+    name: dc1
+    internal: *fiber
+    external: *fiber
+
+servers:
+  - name: dc1s1
+    zone: *dc1
+  - name: dc1s2
+    zone: *dc1
+  - name: dc1s3
+    zone: *dc1
+  - name: dc1s4
+    zone: *dc1
+  - name: dc1s5
+    zone: *dc1
+
+global:
+  subnet:
+    base: 'fc00:9a7a:9e::'
+    local: 64
+    zone: 16
+  latency-offset: 3ms
+  upstream:
+    ip: fc00:9a7a:9e:ffff:ffff:ffff:ffff:ffff
+    conn: *fiber
+
diff --git a/topo/single-dc.yml b/topo/single-dc.yml
deleted file mode 100644
index 39427aa..0000000
--- a/topo/single-dc.yml
+++ /dev/null
@@ -1,34 +0,0 @@
-links:
-  - &fiber
-    bandwidth: 100M
-    latency: 50ms
-    jitter: 10ms
-
-zones:
-  - &dc1
-    name: dc1
-    internal: *fiber
-    external: *fiber
-
-servers:
-  - name: dc1s1
-    zone: *dc1
-  - name: dc1s2
-    zone: *dc1
-  - name: dc1s3
-    zone: *dc1
-  - name: dc1s4
-    zone: *dc1
-  - name: dc1s5
-    zone: *dc1
-
-global:
-  subnet:
-    base: 'fc00:9a7a:9e::'
-    local: 64
-    zone: 16
-  latency-offset: 3ms
-  upstream:
-    ip: fc00:9a7a:9e:ffff:ffff:ffff:ffff:ffff
-    conn: *fiber
-
-- 
cgit v1.2.3