From 2c1f1553286c79467c9d7e7b0789d4e3b2914c4c Mon Sep 17 00:00:00 2001
From: Luna <git@l4.pm>
Date: Fri, 16 Feb 2024 17:56:06 -0300
Subject: [PATCH] update README

---
 README.md  | 51 +++++++++++++++++++++++++++++++++++++++++++--------
 nginx.conf |  2 +-
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 2de4b84..c5bd565 100644
--- a/README.md
+++ b/README.md
@@ -19,8 +19,37 @@ It is an effective replacement to your NGINX installation, but you can have
 them coexisting (say, NGINX on port 80, OpenResty being reverse proxied by
 NGINX on port 8069, though I wouldn't recommend it in production environments).
 
+### how does it work
+
+aproxy has two "hooks" into openresty:
+ - initialization of the lua vm
+ - callback for every incoming request
+
+initialization will run validation of your configuration file and check
+if it is valid. if it is not you will see logs emitted about what failed
+
+when a request comes in, the scripts declared in the aproxy config file will
+be executed sequentially (TODO: ensure order on conf file is chain order).
+
+each script has two types of callbacks: init and request
+
+init callbacks are called when initializing the request, so that the script
+may do some conversion or transform the config data into a more performant
+in-memory structure.
+
+request callbacks are called on each request, as directed by the main script.
+scripts define which paths they want to attach to (via PCRE regex), and so
+they can do their own filtering.
+
+look at `scripts/webfinger_allowlist.lua` for an example of how this looks
+in a simple form.
+
 ### actually installing aproxy
 
+- get openresty installed
+  - keep in mind that the specifics of configuring openresty for a double reverse proxy setup aren't included here.
+  - instructions here are for aproxy's setup in an existing openresty installation
+
 ```sh
 mkdir /opt
 git clone https://gitdab.com/luna/aproxy
@@ -28,6 +57,9 @@ git clone https://gitdab.com/luna/aproxy
 cd aproxy
 mkdir /etc/aproxy
 cp ./conf.lua /etc/aproxy/conf.lua
+
+# keep in mind the default configuration will lead to your users not being discovered at all,
+# it is provided as an example for you to modify.
 $EDITOR /etc/aproxy/conf.lua
 ```
 
@@ -51,21 +83,24 @@ http {
 
 You need to do the following:
  - Configure OpenResty package path so that it can call aproxy.
- - Insert aproxy as a callback on `location / {` block
+ - insert aproxy hooks for initialization and for callbacks on every request
 
-It'll look something like this:
+It'll look something like this if you use a single `location /` block:
 
 ```nginx
+# set this to 'on' after you have tested that it actually works.
+# once you do that, performance will be increased
+# while the friction to quickly debug aproxy will also be increased
+lua_code_cache off;
+lua_package_path '/opt/?.lua;/opt/aproxy/?.lua;;';
+init_by_lua_block {
+  require("aproxy.main").init()
+}
+
 http {
-    lua_package_path '/opt/?.lua;/opt/aproxy/?.lua;;';
-        
     server {
         server_name example.com;
         location / {
-            # set this to 'on' after you have tested that it actually works.
-            # once you do that, performance will be increased
-            # while the friction to quickly debug aproxy will also be increased
-            lua_code_cache off;
             access_by_lua_block {
                 require("aproxy.main").access()
             }
diff --git a/nginx.conf b/nginx.conf
index 4b6e8bf..4904508 100644
--- a/nginx.conf
+++ b/nginx.conf
@@ -1,10 +1,10 @@
+lua_code_cache off;
 init_by_lua_block {
   require("aproxy.main").init()
 }
 
 server {
     listen 80;
-    lua_code_cache off;
 
     location / {
       default_type text/html;