Initial MPQUIC-FEC + stream_multiplexer

BUILDING.md

@@ -0,0 +1,64 @@
+Building
+========
+
+This suite consists of several interlocked packages.
+
+MPQUIC-FEC
+----------
+
+Folder: `src/`
+
+This project was forked from https://bitbucket.org/michelfra/quic-fec/src/networking_2019/
+which in turn is a fork of https://github.com/lucas-clemente/quic-go
+
+Most likely you'll just want to include this as a module in your projects. You
+may look into `src/experiments/delay-server` or `src/experiments/delay-client`
+for an example of this.
+
+You can build both of those applications. Navigate into their respective
+directories and run `go build`.
+
+To include the locally modified version of the module as
+`github.com/lucas-clemente/quic-go` in other projects, add the following to
+their `go.mod` file:
+
+* An entry in the `require` block: `github.com/lucas-clemente/quic-go v0.0.0`
+* A line at the end: `replace github.com/lucas-clemente/quic-go => ../src`
+    * `../src` in this case is the relative path of MPQUIC-FEC from your
+      project
+    * You can modify this as necessary
+
+Caddy Web Server
+----------------
+
+Folder: `caddy/`
+
+This was forked from https://github.com/caddyserver/caddy version `v1.0.5`.
+Newer version of Caddy performed major refactoring, so compatibility will be
+very limited.
+
+Building will have to be performed from the `caddy/` subdirectory (thus
+`caddy/caddy/`). Navigate into it and run `go build`.
+
+
+Python Proxy Shared Library
+---------------------------
+
+Folder: `proxy_module/`
+
+This implements a C compatible shared library in Go. It builds a bridge between
+MPQUIC-FEC and Python. Building this requires a slightly more involved `build`
+command:
+
+```sh
+go build -o proxy_module.so -buildmode=c-shared proxy_module.go
+```
+
+This produces a file called `proxy_module.so`. Copy it into the `astream/`
+directory.
+
+**Attention:** In contrast to other Go binaries, this can never be statically
+linked (CGO will have to be used to create a shared library). Therefore the
+output is not as portable as other Go binaries. If necessary you'll have to build
+this one directly on your experimentation machine. This can be, for example,
+necessary if your local and experiment machine use a different libc version.

README.md

@@ -1,3 +1,109 @@
-# MAppLE (MPQUIC Application Latency Evaluation platform)
+MAppLE (MPQUIC Application Latency Evaluation platform)
 
 A unified MPQUIC Application Latency Evaluation platform (MAppLE) to evaluate and develop MPQUIC with modular multiplexers, stream schedulers, and packet schedulers.
+
+
+MPQUIC-FEC
+==========
+
+This suite implements a testbed for multi-path QUIC with Forward Erasure
+Correction. The main application is a DASH video stream on HTTP2 over QUIC.
+
+Go version 1.14 was used during development. Everything was compiled and run
+under Linux on x86_64.
+
+MPQUIC-FEC
+----------
+
+The MPQUIC-FEC implementation itself can be found in the `src` directory. Go
+modules are used to handle external dependencies.
+
+DASH Server
+-----------
+
+_Caddy_ is used as the HTTP2 server and can be found in the `caddy` directory.
+Its `go.mod` file is setup in such a way that the local MPQUIC-FEC
+implementation is used.
+
+DASH Stream
+-----------
+
+Files relevant to the DASH stream can be found in the `dash` sub directory. To
+host, run _Caddy_ from here, as it searches for the `Caddyfile` in the current
+working directory.
+
+Because you may want to inspect packets with Wireshark, a specific certificate
+should be used by Caddy. Generate a self-signed keypair using OpenSSL. This can
+be automatically done with the `makecert.sh` script. Use the default for each
+option except `CN`. Set the common name of the certificate to the initial IP
+you want to open the multipath connection on. E.g. if the connection is opened
+on `https://10.1.1.1:4242`, set the `CN` to `10.1.1.1`. Don't use hostnames,
+they cause issues with the testbed.
+
+A video is not provided, but can be encoded and prepared for DASH using
+`ffmpeg`. Run the `prepare_video.sh` shell script. On the first run it will
+download the source video from `http://www.jell.yfish.us`. ffmpeg version
+n4.2.3 was used during development.
+
+It outputs the encoded video segments and the DASH manifest into the `video`
+sub directory, which can then be hosted by _Caddy_.
+
+To use all features in caddy (QUIC, multipath, FEC, etc.) use the following
+set of parameters:
+
+```sh
+./caddy -quic -mp -scheduler s-edpf -fec --fecConfig win-xor
+```
+
+DASH Client
+-----------
+
+_AStream_'s client portion is used to access the DASH stream. Here, it is
+ported to Python3. Python 3.6 is the lowest version the software was tested
+with.
+
+An additional proxy module is required to allow using MPQUIC-FEC in _AStream_.
+The module can be found in the `proxy_module` sub directory. To build, navigate
+into this sub directory and execute:
+
+```sh
+go build -o proxy_module.so -buildmode=c-shared proxy_module.go
+```
+
+Copy then the binary `proxy_module.so` into `astream/`
+
+`dash_client.py` is the entry point to _AStream_.
+
+```sh
+python3 astream/dash_client.py -q -mp -m https://10.1.1.1/manifest.mpd -s s-edpf --fec --fecConfig win-xor
+```
+
+Testbed
+-------
+
+Evaluations were performed on Emulab. The utilized testbed descriptions are
+found in the `testbed` sub directory.
+
+The configuration used in the experiments is `experiment-moongen.tcl`. It is
+made to use two moongen based delay nodes. Those form two connections from the
+client to the intermediate router and simulate different link properties.
+
+S-EDPF
+------
+
+The implementation of S-EDPF is found in the `src` directory. It is split into
+two Go packages due to the testbed's code structure.
+
+The employed statistical methods are found in `src/sedpf/`. In contrast, the
+multipath scheduler itself is found in the file `src/scheduler_sedpf.go`
+
+S-IOD
+------
+
+Currently the implementation of S-IOD lives in `src/scheduler_iod.go`. The main
+function is `SelectPathsAndOrder`. In contrast to other scheduling functions
+this also prepares the actual packets in order to interweave with the FEC
+framework. The return value is a list of the packets to be sent and their
+respective paths.  They are already ordered per-path and are actually sent in
+parallel via goroutines. One such routine is spawned per path, allowing packets
+to be sent out of order via multiple paths simultaneously.

RLNC.md

@@ -0,0 +1,22 @@
+Random Linear Network Coding
+============================
+
+The implementation of this coding scheme has inherent issues. Whereas packets,
+when using XOR or Reed-Solomon coding, are marked with BlockID, RLNC does not
+use such a method at all. It instead relies only on packets arriving roughly
+in-order.
+
+Out-of-order arrivials can therefore be handled easily in the other two
+schemes. The encoded BlockID makes it simple to order arriving packets into
+their respective encoded blocks. For RLNC this works as long as only packets
+belonging into the same coding window arrive out-of-order. If several disjunct
+window positions get mixed up, there is no method to correctly map packets. In
+such cases the scheme may still try to recover data, but fails. This produces
+malformed, quasi random bytes which the packet decoding framework then tries to
+decode as a regular QUIC packet. At best (!) this causes a crash. At worst,
+the packet suggests a wrong stream offset or packet number. This will cause the
+receiver to wait for preceding information that will never arrive, timing out
+after a long while.
+
+Especially with IOD family schedulers such events are likely to occur. But even
+LowRTT may cause them.