From 236653b7bc419c519da8d479abc0c78d0a748c4c Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Mon, 21 Mar 2016 11:27:20 +0000
Subject: [PATCH] cgi-fcgi-perl: wip, doc comment

---
 cprogs/cgi-fcgi-perl.c | 57 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 cprogs/cgi-fcgi-perl.c

diff --git a/cprogs/cgi-fcgi-perl.c b/cprogs/cgi-fcgi-perl.c
new file mode 100644
index 0000000..62c5831
--- /dev/null
+++ b/cprogs/cgi-fcgi-perl.c
@@ -0,0 +1,57 @@
+/*
+ * "Interpreter" that you can put in #! like this
+ *   #!/usr/bin/cgi-fcgi-perl [<options>]
+ *
+ * The result is a program which looks, when executed via the #!
+ * line, like a CGI program.  But the perl script inside will
+ * be executed via /usr/bin/perl in fcgi.
+ *
+ * Options:
+ *
+ *  -M<ident>
+ *          Use <ident> rather than hex(sha256(<script>))
+ *          as the basename of the leafname of the fcgi rendezvous
+ *          socket.  If <ident> contains only hex digit characters it
+ *          ought to be no more than 32 characters.
+ *
+ *  -M<numservers>
+ *         Start <numservers> instances of the program.  This
+ *         determines the maximum concurrency.  (Note that unlike
+ *         speedy, the specified number of servers is started
+ *         right away.)  The default is 4.
+ *
+ * cgi-fcgi-perl automatically expires old sockets, including
+ * ones where the named perl script is out of date.
+ */
+
+/*
+ * Uses one of two directories
+ *   /var/run/user/<UID>/cgi-fcgi-perl/
+ *   ~/.cgi-fcgi-perl/<node>/
+ * and inside there uses these paths
+ *   s<ident>
+ *   g<inum>
+ *
+ * If -M<ident> is not specified then an initial substricg of the
+ * lowercase hex of the sha256 of the <script> (ie, our argv[1]) is
+ * used.  The substring is chosen so that the whole path is 10 bytes
+ * shorter than sizeof(sun_path).  But always at least 33 characters.
+ *
+ * Algorithm:
+ *  - see if /var/run/user exists
+ *       if so, lstat /var/run/user/<UID> and check that
+ *         we own it and it's X700; if not, fail
+ *         if it's ok then <base> is /var/run/user/<UID>
+ *       otherwise, look for and maybe create ~/.cgi-fcgi-perl
+ *         (where ~ is HOME or from getpwuid)
+ *         and then <base> is ~/.cgi-fcgi-perl/<node>
+ *  - calculate pathname (checking <ident> length is OK)
+ *  - check for and maybe create <base>
+ *  - stat and lstat the <script>
+ *  - stat the socket and check its timestamp
+ *       if it is too hold, rename it to g<inum> (where
+ *       <inum> is in decimal)
+ *       and run garbage collection
+ *  - run  cgi-fcgi -connect SOCKET SCRIPT
+ */
+
-- 
2.30.2