Add additional debugging instructions (#12)

Author: duffn

README.md

@@ -50,7 +50,7 @@ Remove all query parameters by passing in an empty string.
 ```
 import querymodifier;
 set req.url = querymodifier.modifyparams(url=req.url, params="", exclude_params=true);
-# Or use the conveniecen function, `excludeallparams`.
+# Or use the convenience function, `excludeallparams`.
 # set req.url = querymodifier.excludeallparams(url=req.url);
 
 # Original URL: example.com/?search=name&ts=123456789&v=123456789&id=987654321
@@ -80,6 +80,8 @@ I'm happy to review any PRs. Any bug reports are also welcome.
 
 ### Debugging
 
+#### ASan
+
 The module can also be built with [`AddressSanitizer`](https://github.com/google/sanitizers/wiki/AddressSanitizer) support.
 
 It is recommended that when developing on the module, you build with `AddressSanitizer` support enabled in order to help identify any memory issues with the VMOD.
@@ -94,9 +96,47 @@ There are also some scripts in the `debug` directory to assist. Navigate to the
 
 _Note_: Do not use the module built with ASan support in production. This is meant for development purposes only.
 
+#### gdb
+
+`gdb` is also included in the debug Dockerfile for your convenience.
+
+- After you've brought up Docker Compose, exec into the Varnish container.
+
+```bash
+docker compose exec varnish
+```
+
+- Attach `gdb` to the Varnish child process. You can either get the PID with `ps` or Varnish will print the child PID to the console like `varnish-1  | Debug: Child (31) Started`.
+
+```bash
+(gdb) attach 31
+```
+
+- Set a breakpoint, for example on the `vmod_modifyparams` function. A `.gdbinit` file is included in the Docker container to instruct `gdb` where to find the VMOD shared libraries.
+
+```bash
+(gdb) b vmod_modifyparams
+Breakpoint 1 at 0xffff7e0b14cc: file vmod_querymodifier.c, line 219.
+```
+
+- Send a request to `http://localhost:8080` that exercises the VMOD.
+
+- Continue the debugger and then use `gdb` as you normally would.
+
+```bash
+(gdb) c
+Continuing.
+[Switching to Thread 0xffff855cf140 (LWP 372)]
+
+Thread 101 "cache-worker" hit Breakpoint 1, vmod_modifyparams (ctx=0xffff855cd9b8, uri=0xffff79a3d8ac "/?blah=1&ts=1", params_in=0xffff7e0e7610 "ts,v,cacheFix,date",
+    exclude_params=1) at vmod_querymodifier.c:219
+219         CHECK_OBJ_NOTNULL(ctx, VRT_CTX_MAGIC);
+```
+
 ## Acknowledgements
 
 - The NY Times [`libvmod-queryfilter` VMOD](https://github.com/nytimes/libvmod-queryfilter/) for insipiration.
+- dridi [`vmod-querystring` VMOD](https://git.sr.ht/~dridi/vmod-querystring) for insipiration.
 - [`vcdk`](https://github.com/nigoroll/vcdk/) for the project structure.
 - Guillaume Quintard for the [VMOD tutorial](https://info.varnish-software.com/blog/creating-a-vmod-vmod-str).
 

debug/.gdbinit

@@ -0,0 +1 @@
+set solib-search-path /var/lib/varnish/varnishd/vmod_cache

debug/Dockerfile

@@ -9,12 +9,14 @@ RUN apt-get update && \
     automake \
     python3-docutils \
     autoconf-archive \
-    libasan8
+    libasan8 \
+    gdb \
+    procps
 
 WORKDIR /
 
 COPY . /libvmod-querymodifier
 RUN cd /libvmod-querymodifier \
-	&& ./bootstrap --enable-asan \
+	&& ./bootstrap --enable-asan CFLAGS="-g -O0" \
 	&& make \
 	&& make install

debug/docker-compose.yml

@@ -11,6 +11,11 @@ services:
     volumes:
       - ./default.vcl:/etc/varnish/default.vcl
       - ./entrypoint.sh:/entrypoint.sh
+      - ./.gdbinit:/root/.gdbinit
+    cap_add:
+      - SYS_PTRACE
+    security_opt:
+      - seccomp=unconfined
   nginx:
     image: nginx:1.27-alpine
     ports: