geomyidae

A small C-based gopherd. (gopher://bitreich.org/1/scm/geomyidae)
git clone git://r-36.net/geomyidae
Log | Files | Refs | README | LICENSE

CGI.md (4280B)


      1 # Introduction to CGI
      2 
      3 Geomyidae has  support for running  scripts on each request,  which will
      4 generate dynamic content.
      5 
      6 There are three modes: standard cgi, dynamic cgi and http compatibility
      7 mode. (»CGI« as name was just taken, because that's easier to compare
      8 to the web.)
      9 
     10 
     11 ## Permissions
     12 
     13 The scripts are run using the permissions of geomyidae. It is advised to
     14 use the -g and -u options of geomyidae.
     15 
     16 
     17 ## Beforehand
     18 
     19 In these examples C: is what the client sends and S: what the server is
     20 sending.
     21 
     22 ## Stdout/Stdin I/O of the Scripts
     23 
     24 All scripts called below, in TLS or Non-TLS mode, will get full access of
     25 the socket of the connection, with the socket bound to stdin and stdout.
     26 Geomyidae does not check for any connection duration. This allows to
     27 create long-lasting streaming services, like radio or TV stations.
     28 
     29 ## Calling Convention
     30 
     31 Geomyidae will call the script like this:
     32 
     33 	% $gopherroot/test.cgi $search $arguments $host $port $traversal
     34 			$selector
     35 
     36 When it is a plain request, the arguments will have these values:
     37 
     38 	C: /test.cgi
     39 	-> $search = ""
     40 	-> $arguments = ""
     41 	-> $host = server host
     42 	-> $port = server port
     43 	-> $traversal = ""
     44 	-> $selector = "/test.cgi"
     45 
     46 If the request is for a type 7 search element, then the entered string by
     47 the user will be seen as following:
     48 
     49 	C: /test.cgi	searchterm		(There is a TAB in-between)
     50 	-> $search = »searchterm«
     51 	-> $arguments = ""
     52 	-> $host = server host
     53 	-> $port = server port
     54 	-> $traversal = ""
     55 	-> $selector = "/test.cgi\tsearchterm"
     56 
     57 When you are trying to give your script some calling arguments, the syntax
     58 is:
     59 
     60 	C: /test.cgi?hello
     61 	-> $search = ""
     62 	-> $arguments = "hello"
     63 	-> $host = server host
     64 	-> $port = server port
     65 	-> $traversal = ""
     66 	-> $selector = "/test.cgi?hello"
     67 
     68 If both ways of input are combined, the variables are set as following:
     69 
     70 	C: /test.cgi?hello=world	searchterm	(Beware! A Tab!)
     71 	-> $search = "searchterm"
     72 	-> $arguments = "hello=world"
     73 	-> $host = server host
     74 	-> $port = server port
     75 	-> $traversal = ""
     76 	-> $selector = "/test.cgi?hello=world\tsearchterm"
     77 
     78 ## REST Calling Convention
     79 
     80 There is a special mode in geomyidae to imitate REST calling abilities.
     81 
     82 When a user requests some non-existing path, geomyidae will start from
     83 the base and go up the path directories, until it reaches the first not
     84 existing directory.
     85 
     86 	C: /base/some/dir/that/does/not/exist?some-arguments	searchterm
     87 	-> base exists
     88 	-> some exists
     89 	-> dir does not exist
     90 	-> search for index.cgi or index.dcgi in /base/some
     91 	-> if found, call index.cgi or index.dcgi as follows:
     92 		-> $search = "searchterm"
     93 		-> $arguments = "some-arguments"
     94 		-> $host = server host
     95 		-> $port = server port
     96 		-> $traversal = "/dir/that/does/not/exist"
     97 		-> $selector = "/base/some/dir/that/does/not/exist?some-arguments\tsearchterm"
     98 
     99 ## Standard CGI
    100 
    101 The file  extension "cgi" switches to  this mode, where the  output of
    102 the script is not interpreted at all  by the server and the script needs
    103 to send raw content.
    104 
    105 	% cat test.cgi
    106 	#!/bin/sh
    107 	echo "Hello my friend."
    108 	%
    109 
    110 The client will receive:
    111 
    112 	S: Hello my friend.
    113 
    114 
    115 ## Dynamic CGI
    116 
    117 For using  dynamic CGI, the  file needs to  end in "dcgi",  which will
    118 switch on  the interpretation of the  returned lines by the  server. The
    119 interpreted for- mat is the same as in the .gph files.
    120 
    121 	% cat test.dcgi
    122 	#!/bin/sh
    123 	echo "[1|Some link|/somewhere|server|port]"
    124 	%
    125 
    126 Here  geomyidae will  interpret the  .gph format  and return  the valid
    127 gopher menu item.
    128 
    129 	S: 1Some link	/somewhere	gopher.r-36.net	70
    130 
    131 ## HTTP Compatibility
    132 
    133 In case someone sends some HTTP request to geomyidae and other cases,
    134 geomyidae will do this:
    135 
    136 	C: GET /some/dir HTTP/1.1
    137 	-> /GET does exist and is executable
    138 	-> call GET as follows:
    139 		-> $search = ""
    140 		-> $arguments = ""
    141 		-> $host = server host
    142 		-> $port = server port
    143 		-> $traversal = ""
    144 		-> $selector = "GET /some/dir HTTP/1.1\r\n"
    145 		   (full raw request by the client.)
    146 
    147 This allows to serve HTTP next go gopher and get TLS for free. Other
    148 HTTP-like protocols can be used over gopher in simple scripts, like the
    149 icecast upload protocol.
    150 
    151 ## Environment Variables
    152 
    153 Please see the manpage geomyidae(8) for all variables and their content.
    154 All states of the script execution environment and client request are
    155 available.
    156 
    157 
    158 Have fun!
    159