From fbeb734571d738cea822c75b217350220ba80302 Mon Sep 17 00:00:00 2001 From: Christian Hesse Date: Wed, 26 May 2021 09:31:58 +0200 Subject: document request flow --- FLOW.md | 38 ++++ FLOW/fail.svg | 588 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ FLOW/ok.svg | 588 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 2 + README.md | 3 + 5 files changed, 1219 insertions(+) create mode 100644 FLOW.md create mode 100644 FLOW/fail.svg create mode 100644 FLOW/ok.svg diff --git a/FLOW.md b/FLOW.md new file mode 100644 index 0000000..7fd1f9b --- /dev/null +++ b/FLOW.md @@ -0,0 +1,38 @@ +pacredir - request flow +======================= + +[◀ Go back to main README](README.md) + +Whenever `pacman` sends a request to `pacredir` a number of requests +(increasing with the number of hosts found) is sent through the network. +Let's assume `pacredir` knows about two hosts. + +OK - serving from local network +------------------------------- + +In this exemple one hast (`host A`) is missing the file, but second +one (`host B`) does have the file. + +For database files the decision on what return code (`307` vs. `404`) to +send is made on the file age. The local file's timestamp is compared to +what timestamp `pacman` sends in its request. + +![OK - serving from local network](FLOW/ok.svg) + +After the initial request `pacman` is redirected to `host B` and gets the +file there. No request is sent to the mirror. + +FAIL - fallback to mirror +------------------------- + +In this example no host has the file or the local database files are older +than what `pacman` requested. + +![FAIL - fallback to mirror](FLOW/fail.svg) + +All requests made by `pacredir` are answered with http code `404`, thus +`pacman` receives the same. Finally `pacman` falls back to the next mirror. + +--- +[◀ Go back to main README](README.md) +[▲ Go back to top](#top) diff --git a/FLOW/fail.svg b/FLOW/fail.svg new file mode 100644 index 0000000..c20be32 --- /dev/null +++ b/FLOW/fail.svg @@ -0,0 +1,588 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + localhost + + + + pacman + + + + pacredir + + + + + host Apacserve + + + + host Bpacserve + + + + mirror + + + + + GET + + + + + HEAD + + + + + HEAD + + + + + 404 + + + + + 404 + + + + + 404 + + + + + GET + + + + + 200 + + + diff --git a/FLOW/ok.svg b/FLOW/ok.svg new file mode 100644 index 0000000..0f349f2 --- /dev/null +++ b/FLOW/ok.svg @@ -0,0 +1,588 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + localhost + + + + pacman + + + + pacredir + + + + + host Apacserve + + + + host Bpacserve + + + + mirror + + + + + GET + + + + + HEAD + + + + + HEAD + + + + + 404 + + + + + 200 + + + + + 307 + + + + + GET + + + + + 200 + + + diff --git a/Makefile b/Makefile index f4e28b5..ae09b42 100644 --- a/Makefile +++ b/Makefile @@ -69,6 +69,8 @@ install-bin: pacredir avahi/pacserve.service install-doc: $(HTML) $(INSTALL) -d -m0755 $(DESTDIR)$(PREFIX)/share/doc/pacredir/ $(INSTALL) -D -m0644 $(MARKDOWN) $(HTML) -t $(DESTDIR)$(PREFIX)/share/doc/pacredir/ + $(INSTALL) -d -m0755 $(DESTDIR)$(PREFIX)/share/doc/pacredir/FLOW/ + $(INSTALL) -D -m0644 $(wildcard FLOW/*) -t $(DESTDIR)$(PREFIX)/share/doc/pacredir/FLOW/ clean: $(RM) -f *.o *~ pacredir avahi/pacserve.service $(HTML) version.h diff --git a/README.md b/README.md index 3907feb..4bcc937 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,9 @@ Please note that `pacredir` redirects to the most recent file found on the local network. To make sure you really do have the latest files run `pacman -Syu` *twice*. +To get a better idea what happens in the background have a look at +[the request flow chart](FLOW.md). + Security -------- -- cgit v1.2.3-54-g00ecf