From 49812df8ccd798598b747ca8958b413067bbe540 Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Sun, 3 Oct 2021 19:52:39 +0300 Subject: [PATCH] Initial documentation --- doc/.gitignore | 1 + doc/index.texi | 170 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/style.css | 9 +++ doc/www.do | 15 +++++ 4 files changed, 195 insertions(+) create mode 100644 doc/.gitignore create mode 100644 doc/index.texi create mode 100644 doc/style.css create mode 100644 doc/www.do diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..b3f4d30 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +/godlighty.html diff --git a/doc/index.texi b/doc/index.texi new file mode 100644 index 0000000..abf9c20 --- /dev/null +++ b/doc/index.texi @@ -0,0 +1,170 @@ +\input texinfo +@documentencoding UTF-8 +@settitle godlighty + +@copying +Copyright @copyright{} 2021 @email{stargrave@@stargrave.org, Sergey Matveev} +@end copying + +@node Top +@top godlighty + +@command{godlighty} is highly-customizable HTTP, HTTP/2, HTTPS server +written on pure Go. + +Why yet another web-server? Because all others suck even for my simple +ordinary needs: they use hateful OpenSSL, lacks documentation, has +complex configuration format, lack some features, hard to extend with. + +@itemize + +@item Rather minimalistic pure-Go web-server with few number of +dependencies, producing single statically linked executable. Maximal +reuse of native libraries capabilities. + +@item Modern, reliable, secure and fast TLS 1.3 implementation with +ChaCha20-Poly1305, session resumption and GOST cryptography (if built +with @url{http://www.gostls13.cypherpunks.ru/, gostls13}). SNI supported. + +@item HTTP/1.1, @url{https://en.wikipedia.org/wiki/HTTP%2F2, HTTP/2} +(only when negotiated during ALPN) and keepalives support. + +@item @code{gzip} and @url{https://facebook.github.io/zstd/, Zstandard} +compression on-the-fly. + +@item @code{Range}, @code{ETag} (based on file/directory's +@code{ctime}), @code{Last-Modified} and corresponding precondition +handlers are fully used. + +@item Auto-generated directory listings and +read-only @url{https://en.wikipedia.org/wiki/WebDAV, WebDAV} support. + +@item If corresponding @file{.meta4} files are found, then @code{Link} +header is generated automatically to that +@url{http://www.metalinker.org/, Metalink}. + +@item Very friendly to @url{http://cr.yp.to/daemontools.html, daemontools}. +Can drop (UID, GID, groups) privileges. + +@end itemize + +Basically all configuration is done directly inside source code. +Initially @command{godlighty} has basic static files handlers (with +compression, HTTP preconditions are enabled of course). In the example +below there are nearly all default functions. + +@verbatim +Hosts["example.com"] = &godlighty.HostCfg{ + Root: "/www/example.com", + TLS: &godlighty.TLSCfg{ + Cert: "/path/to/example.com.pem", + Key: "/path/to/example.com.key.pem", + CACert: "/path/to/ca.pem", + }, + DirList: true, + WebDAV: true, + MIMEOverride: map[string]string{ + ".special": "text/x-special-type", + }, +} +@end verbatim + +If your keys and certificates are in single file and you use common CA +certificate, then it is trivial to DRY: + +@verbatim +var ( + Etc = "/whatever" + CACert = path.Join(Etc, "ca.pem") +) + +func newTLSCfg(host string) *godlighty.TLSCfg { + return &godlighty.TLSCfg{ + Cert: path.Join(Etc, host+".pem"), + Key: path.Join(Etc, host+".pem"), + CACert: CACert, + } +} +@end verbatim + +But there are hooks that can do anything more. For example if you want +to run CGI script or make a redirection: + +@verbatim +HostCfg{ + ..., + Hooks: []godlighty.Hook{ + func(w http.ResponseWriter, r *http.Request) bool { + if r.URL.Path == "/" { + http.Redirect(w, r, "//here.we.go/", http.StatusMovedPermanently) + return true + } + return false + }, + func(w http.ResponseWriter, r *http.Request) bool { + cgi.Handler{ + Path: "/usr/local/libexec/git-core/git-http-backend", + Dir: "/var/empty", + Env: []string{ + "GIT_PROJECT_ROOT=" + root, + "GIT_HTTP_EXPORT_ALL=", + }, + }.ServeHTTP(w, r) + return true + }, + }, +@end verbatim + +You can separate your configuration files and add them through +@code{init()} call: + +@verbatim +$ ls rc +blog.stargrave.org.go +ca.cypherpunks.ru.go +cgi.go +cryptoanarchy.ru.go +git.go +go.go +if.mirror.cypherpunks.ru.go +lists.cypherpunks.ru.go +mime.go +static.go +tls.go +[...] + +$ cat rc/static +package rc + +import "path" + +func addStaticCfg(host, root string) { + if !path.IsAbs(root) { + root = path.Join(WWW, root) + } + godlighty.Hosts[host] = &godlighty.HostCfg{ + Root: root, + TLS: newTLSCfg(host), + } +} + +func addStaticListedDir(host, root string) { + addStaticCfg(host, root) + godlighty.Hosts[host].DirList = true + godlighty.Hosts[host].WebDAV = true +} + +func init() { + [...] + addStaticCfg("paster.stargrave.org", "/storage/paster/pastes") + addStaticCfg("www.godlighty.stargrave.org", "godlighty.stargrave.org") + addStaticCfg("www.nncpgo.org", "nncpgo.org") + addStaticListedDir("www.mds.cypherpunks.ru", "/storage/audiobook/mds") + [...] +} +@end verbatim + +It is created exclusively to drive my own websites, but if you are +interested, then @code{git clone git://git.stargrave.org/godlighty.git} it. + +@bye diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..0d2e65b --- /dev/null +++ b/doc/style.css @@ -0,0 +1,9 @@ +body { + margin: auto; + width: 80em; + background-color: #AEBECE; +} +h1, h2, h3, h4 { text-align: center } +h1, h2, h3, h4, strong { color: #900090 } +pre { background-color: #CCCCCC } +table, th, td { border: 1px solid black ; border-collapse: collapse } diff --git a/doc/www.do b/doc/www.do new file mode 100644 index 0000000..757263e --- /dev/null +++ b/doc/www.do @@ -0,0 +1,15 @@ +redo-ifchange *.texi +html=godlighty.html +rm -f $html/*.html +${MAKEINFO:=makeinfo} --html \ + --css-include style.css \ + --set-customization-variable SECTION_NAME_IN_TITLE=1 \ + --set-customization-variable TREE_TRANSFORMATIONS=complete_tree_nodes_menus \ + --set-customization-variable FORMAT_MENU=menu \ + --set-customization-variable SHOW_TITLE=0 \ + --set-customization-variable DATE_IN_HEADER=1 \ + --set-customization-variable CLOSE_QUOTE_SYMBOL=\" \ + --set-customization-variable OPEN_QUOTE_SYMBOL=\" \ + -o $html index.texi +find $html -type d -exec chmod 755 {} + +find $html -type f -exec chmod 644 {} + -- 2.44.0