Update CGI to the current state and restyle it. - geomyidae - A small C-based gopherd.
HTML git clone git://bitreich.org/geomyidae/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/geomyidae/
DIR Log
DIR Files
DIR Refs
DIR Tags
DIR README
DIR LICENSE
---
DIR commit 7bb98e044757e47523468791f8f4040893c34342
DIR parent 1f99de32eae25260f0596aad2c33780a239ba999
HTML 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(-)
---
DIR 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!