geomyidae

commit 7bb98e044757e47523468791f8f4040893c34342
parent 1f99de32eae25260f0596aad2c33780a239ba999
Author: Christoph Lohmann <20h@r-36.net>
Date:   Sat, 22 Jul 2023 18:07:39 +0200

Update CGI to the current state and restyle it.

Diffstat:
M
CGI.md
 | 
86
++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------

1 file changed, 59 insertions(+), 27 deletions(-)
diff --git a/CGI.md b/CGI.md
@@ -1,29 +1,37 @@
-# INTRODUCTION TO CGI
+# Introduction to CGI
 
 Geomyidae has  support for running  scripts on each request,  which will
 generate dynamic content.
 
-There are two modes: standard cgi  and dynamic cgi. (»CGI« as name was
-just taken, because that's easier to compare to the web.)
+There are three modes: standard cgi, dynamic cgi and http compatibility
+mode. (»CGI« as name was just taken, because that's easier to compare
+to the web.)
 
 
-## PERMISSIONS
+## Permissions
 
 The scripts are run using the permissions of geomyidae. It is advised to
 use the -g and -u options of geomyidae.
 
 
-## BEFOREHAND
+## Beforehand
 
 In these examples C: is what the client sends and S: what the server is
 sending.
 
+## Stdout/Stdin I/O of the Scripts
 
-## CALLING CONVENTION
+All scripts called below, in TLS or Non-TLS mode, will get full access of
+the socket of the connection, with the socket bound to stdin and stdout.
+Geomyidae does not check for any connection duration. This allows to
+create long-lasting streaming services, like radio or TV stations.
+
+## Calling Convention
 
 Geomyidae will call the script like this:
 
-	% $gopherroot/test.cgi $search $arguments $host $port
+	% $gopherroot/test.cgi $search $arguments $host $port $traversal
+			$selector
 
 When it is a plain request, the arguments will have these values:
 
@@ -32,6 +40,8 @@ When it is a plain request, the arguments will have these values:
 	-> $arguments = ""
 	-> $host = server host
 	-> $port = server port
+	-> $traversal = ""
+	-> $selector = "/test.cgi"
 
 If the request is for a type 7 search element, then the entered string by
 the user will be seen as following:
@@ -41,25 +51,31 @@ the user will be seen as following:
 	-> $arguments = ""
 	-> $host = server host
 	-> $port = server port
+	-> $traversal = ""
+	-> $selector = "/test.cgi\tsearchterm"
 
 When you are trying to give your script some calling arguments, the syntax
 is:
 
 	C: /test.cgi?hello
 	-> $search = ""
-	-> $arguments = »hello«
+	-> $arguments = "hello"
 	-> $host = server host
 	-> $port = server port
+	-> $traversal = ""
+	-> $selector = "/test.cgi?hello"
 
 If both ways of input are combined, the variables are set as following:
 
 	C: /test.cgi?hello=world	searchterm	(Beware! A Tab!)
-	-> $search = »searchterm«
-	-> $arguments = »hello=world«
+	-> $search = "searchterm"
+	-> $arguments = "hello=world"
 	-> $host = server host
 	-> $port = server port
+	-> $traversal = ""
+	-> $selector = "/test.cgi?hello=world\tsearchterm"
 
-## REST CALLING CONVENTION
+## REST Calling Convention
 
 There is a special mode in geomyidae to imitate REST calling abilities.
 
@@ -68,20 +84,21 @@ the base and go up the path directories, until it reaches the first not
 existing directory.
 
 	C: /base/some/dir/that/does/not/exist?some-arguments	searchterm
-	-> /base exists
-	-> /some exists
-	-> /dir does not exist
+	-> base exists
+	-> some exists
+	-> dir does not exist
 	-> search for index.cgi or index.dcgi in /base/some
-	-> if not found, display directory content
 	-> if found, call index.cgi or index.dcgi as follows:
-		-> $search = »searchterm«
-		-> $arguments = »/dir/that/does/not/exist?some-arguments«
+		-> $search = "searchterm"
+		-> $arguments = "some-arguments"
 		-> $host = server host
 		-> $port = server port
+		-> $traversal = "/dir/that/does/not/exist"
+		-> $selector = "/base/some/dir/that/does/not/exist?some-arguments\tsearchterm"
 
-## STANDARD CGI
+## Standard CGI
 
-The file  extension »cgi« switches to  this mode, where the  output of
+The file  extension "cgi" switches to  this mode, where the  output of
 the script is not interpreted at all  by the server and the script needs
 to send raw content.
 
@@ -95,9 +112,9 @@ The client will receive:
 	S: Hello my friend.
 
 
-## DYNAMIC CGI
+## Dynamic CGI
 
-For using  dynamic CGI, the  file needs to  end in »dcgi«,  which will
+For using  dynamic CGI, the  file needs to  end in "dcgi",  which will
 switch on  the interpretation of the  returned lines by the  server. The
 interpreted for- mat is the same as in the .gph files.
 
@@ -111,16 +128,31 @@ gopher menu item.
 
 	S: 1Some link	/somewhere	gopher.r-36.net	70
 
-For outputting  large texts and  having minor hassles with  the content,
-prepend »t« to every line beginning with »t« or all lines:
+## HTTP Compatibility
 
-	% cat filereader.dcgi
-	#!/bin/sh
-	cat bigfile.txt | sed 's,^t,&&,'
+In case someone sends some HTTP request to geomyidae and other cases,
+geomyidae will do this:
+
+	C: GET /some/dir HTTP/1.1
+	-> /GET does exist and is executable
+	-> call GET as follows:
+		-> $search = ""
+		-> $arguments = ""
+		-> $host = server host
+		-> $port = server port
+		-> $traversal = ""
+		-> $selector = "GET /some/dir HTTP/1.1\r\n"
+		   (full raw request by the client.)
+
+This allows to serve HTTP next go gopher and get TLS for free. Other
+HTTP-like protocols can be used over gopher in simple scripts, like the
+icecast upload protocol.
 
-## ENVIRONMENT VARIABLES
+## Environment Variables
 
 Please see the manpage geomyidae(8) for all variables and their content.
+All states of the script execution environment and client request are
+available.
 
 
 Have fun!