Merge branch 'cgi-suport-wip' into 'master'

CGI support

See merge request reidrac/spacebeans!1

1 files changed, 42 insertions, 0 deletions

diff --git a/README.md b/README.md
index 4fcb6a6..319a78c 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,48 @@ secret used when importing the certificate.
 CA signed certificates don't play well with TOFU, but if the client is properly
 validating the certificate, this is perfectly safe.
 
+## CGI support
+
+Classic CGI is supported via the `allow-cgi` flag in the `directories` directive.
+
+The flag only affects to the specified directory.
+
+The environment variables provided to the CGIs are:
+
+| Variable          | Example                                          |
+| ---               | ---                                              |
+| REMOTE_ADDR       | `127.0.0.1`                                      |
+| SERVER_PORT       | `1965`                                           |
+| GEMINI_URL        | `gemini://localhost/mycgi/example/path?test=1`   |
+| REMOTE_HOST       | `127.0.0.1`                                      |
+| SERVER_PROTOCOL   | `GEMINI`                                         |
+| SERVER_SOFTWARE   | `spacebeans/v1.1.3`                              |
+| SCRIPT_NAME       | `mycgi`                                          |
+| SERVER_NAME       | `localhost`                                      |
+| PATH_INFO         | `/example/path`                                  |
+| GATEWAY_INTERFACE | `CGI/1.1`                                        |
+| QUERY_STRING      | `test=1`                                         |
+
+These are described in [RFC-3875](https://datatracker.ietf.org/doc/html/rfc3875).
+
+The server expects:
+
+- the CGI must terminate with exit code `0` (success)
+- the response will be in CGI's standard output
+- it **must** be a valid Gemini response
+
+An example of a CGI script written in Python that outputs the environment
+variables could be:
+
+```python
+#!/usr/bin/env python3
+
+import os
+
+print("20 text/gemini\r\n")
+print('\n'.join([k + "=" + v for k, v in os.environ.items()]))
+```
+
 ## Development
 
 Requirements: