From: Sergey Matveev Date: Fri, 13 Feb 2026 13:36:09 +0000 (+0300) Subject: Convert documentation to SWG X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=5421b46e49e63ce9c562166714871120f520f091;p=godlighty.git Convert documentation to SWG --- diff --git a/doc/.swgignore b/doc/.swgignore new file mode 100644 index 0000000..e90ee87 --- /dev/null +++ b/doc/.swgignore @@ -0,0 +1,2 @@ +^mk-html$ +^godlighty.html/ diff --git a/doc/Configuration b/doc/Configuration new file mode 100644 index 0000000..d2d1b39 --- /dev/null +++ b/doc/Configuration @@ -0,0 +1,119 @@ +Initially godlighty has basic static files handlers (with compression, +HTTP preconditions are enabled of course). In the example below there +are nearly all default functions. Also look for rc/example.cfg. + + Hosts["example.com"] = &godlighty.HostCfg{ + Root: "/www/example.com", + EdDSATLS: &godlighty.TLSCfg{ + Cert: "/path/to/example.com.pem", + Key: "/path/to/example.com.key.pem", + CACert: "/path/to/ca.pem", + }, + DirList: true, + WebDAV: true, + MIMEs: map[string]string{ + ".special": "text/x-special-type", + }, + } + +If your keys and certificates are in single file and you use common CA +certificate, then it is trivial to DRY: + + 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, + } + } + +But there are hooks that can do anything more. For example if you want +to run CGI script or make a redirection (FastCGI handler example is in +rc/fcgi.example.cfg): + + 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 + }, + }, + +You can separate your configuration files and add them through init() call: + + $ ls rc/stargrave.org.cfg + 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 + static.go + tls.go + [...] + + $ cat rc/stargrave.org.cfg/static.go + 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.su", "/storage/audiobook/mds") + [...] + } + +There are some pre-existing helpers to deal with: + +rc/cgi.go + CGI scripts. + +rc/redirect.go + Loggable redirects. + +rc/mime.go, rc/mime/* + Predefined Content-Type entries. Each file in rc/mime/* has + tab-separated format: file's extension, media type and optional + "c" mark, meaning that these type can be transparently compressed + on-the-fly. diff --git a/doc/Usage b/doc/Usage new file mode 100644 index 0000000..4664d87 --- /dev/null +++ b/doc/Usage @@ -0,0 +1,31 @@ +All [Configuration] is assumed to be placed in rc/cfg. Probably you want +to deal with multiple server configurations simultaneously. You place +them in corresponding rc/NAME.cfg directories and use redo default +target to create necessary symbolic link of rc/NAME.cfg to rc/cfg and +build executable itself. + +=> http://cr.yp.to/redo.html + + $ redo example.cmd + # will produce example executable with rc/example.cfg configuration + + $ redo fcgi.example.cmd + # will produce fcgi.example executable with rc/fcgi.example.cfg configuration + +But because you will mostly like to create binary patches to quickly +update already existing binaries, then you can use make-update script, +that will store newly created binaries in updates/ directory and make +shell-script with the built-in binary patch and SHA512 checksum checker: + + # First run + $ ./make-update example + $ scp updates/example.old web-server:/path/to/www-server + + $ ./make-update example + $ scp updates/example-update.sh web-server:/tmp + web-server $ /tmp/example-update.sh /path/to/www-server + web-server $ svc -t /var/service/www-server + +contrib/service contains daemontools example run scripts. + +Send SIGINFO (SIGUSR1 on Linux) signal to get current daemon's configuration. diff --git a/doc/cfg.texi b/doc/cfg.texi deleted file mode 100644 index 530502d..0000000 --- a/doc/cfg.texi +++ /dev/null @@ -1,136 +0,0 @@ -@node Configuration -@unnumbered Configuration - -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. -Also look for @file{rc/example.cfg}. - -@verbatim -Hosts["example.com"] = &godlighty.HostCfg{ - Root: "/www/example.com", - EdDSATLS: &godlighty.TLSCfg{ - Cert: "/path/to/example.com.pem", - Key: "/path/to/example.com.key.pem", - CACert: "/path/to/ca.pem", - }, - DirList: true, - WebDAV: true, - MIMEs: 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 (FastCGI handler example is in -@file{rc/fcgi.example.cfg}): - -@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/stargrave.org.cfg -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 -static.go -tls.go -[...] - -$ cat rc/stargrave.org.cfg/static.go -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 - -There are some preexisting helpers to deal with: - -@table @file - -@item rc/cgi.go -CGI scripts. - -@item rc/redirect.go -Loggable redirects. - -@item rc/mime.go, rc/mime/* -Predefined @code{Content-Type} entries. Each file in @file{rc/mime/*} -has tab-separated format: file's extension, media type and optional -@code{c} mark, meaning that these type can be transparently compressed -on-the-fly. - -@end table diff --git a/doc/index b/doc/index new file mode 100644 index 0000000..bd5c450 --- /dev/null +++ b/doc/index @@ -0,0 +1,52 @@ +godlighty is free software 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, lack documentation, has +complex configuration format, lack some features, hard to extend with. + +* Pretty minimalistic pure-Go web-server with few number of + dependencies, producing single statically linked executable. + Maximal reuse of native libraries capabilities. + +* Modern, reliable, secure and fast TLS 1.3 implementation with + ChaCha20-Poly1305, hybrid PQ/T KEM, session resumption and SNI + (depends on Go version you are using). + +* If built with gostls13, then GOST TLS 1.3 cryptography will be fully + supported, with ability to use GOST-based X.509 certificates if client + announces its knowledge of GOST algorithms (with the fallback to + ordinary ECDSA/EdDSA ones). + => http://www.gostls13.cypherpunks.su/ gostls13 + => http://www.gost.cypherpunks.su/ GOST + +* HTTP/1.1, HTTP/2 (optionally, only when negotiated during ALPN) and + keepalives support. Graceful shutdowns. + +* gzip and Zstandard compression on-the-fly. + +* Range, ETag (based on file/directory's mtime), Last-Modified and + corresponding precondition handlers are fully used. + +* Auto-generated directory listings and read-only WebDAV support. + +* Per-domain HTTP basic authorization and TLS client authentication. + +* If corresponding .meta4 files are found, it is parsed and additional + Links with Digests headers are generated automatically, based on that + Metalink file. + => http://www.metalinker.org/ Metalink + +* Friendly to daemontools. Can drop (UID, GID, groups) privileges. + => http://cr.yp.to/daemontools.html + +Basically all configuration is done directly inside source code. You +have to recompile it every time configuration changes. Is it a problem? +I doubt, because Go is very fast. But it produces huge statically linked +executables, you say! Use either bsdiff/bspatch or zstd --patch-from! + +It is created exclusively to drive my own websites, but if you are +interested, then git clone git://git.stargrave.org/godlighty.git + +[Configuration] +[Usage] diff --git a/doc/index.texi b/doc/index.texi deleted file mode 100644 index e0727fc..0000000 --- a/doc/index.texi +++ /dev/null @@ -1,76 +0,0 @@ -\input texinfo -@settitle godlighty - -@copying -Copyright @copyright{} 2021-2026 @email{stargrave@@stargrave.org, Sergey Matveev} -@end copying - -@node Top -@top godlighty - -@command{godlighty} is -@url{https://www.gnu.org/philosophy/free-sw.html, free software} -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, lack 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 SNI. - -@item If built with @url{http://www.gostls13.cypherpunks.su/, gostls13}, -then @url{http://www.gost.cypherpunks.su/, GOST} TLS 1.3 cryptography -will be fully supported, with ability to use GOST-based X.509 -certificates if client announces its knowledge of GOST algorithms (with -the fallback to ordinary ECDSA/EdDSA ones). - -@item HTTP/1.1, @url{https://en.wikipedia.org/wiki/HTTP%2F2, HTTP/2} -(only when negotiated during ALPN) and keepalives support. Graceful -shutdowns. - - -@item @url{https://en.wikipedia.org/wiki/Gzip, 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 Per-domain HTTP basic authorization and TLS client authentication. - -@item If corresponding @file{.meta4} files are found, it is parsed and -additional @code{Link}s with @code{Digest}s headers are generated -automatically, based on that @url{http://www.metalinker.org/, Metalink} -file. - -@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. You -have to recompile it every time configuration changes. Is it a problem? -I doubt, because Go is very fast. But it produces huge statically linked -executables, you say! Use either @command{bsdiff}/@command{bspatch} or -@command{zstd --patch-from}! - -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. - -@insertcopying - -@include cfg.texi -@include usage.texi - -@bye diff --git a/doc/mk-html b/doc/mk-html new file mode 100755 index 0000000..5c85436 --- /dev/null +++ b/doc/mk-html @@ -0,0 +1,8 @@ +#!/bin/sh + +html=godlighty.html +rm -f $html/*.html +SWG_DO_SRC=0 SWG_DO_BACKS=0 swg htmls $html +perl -i -npe 's#^.*$#<title>godlighty#' $html/index.html +find $html -type d -exec chmod 755 {} + +find $html -type f -exec chmod 644 {} + diff --git a/doc/usage.texi b/doc/usage.texi deleted file mode 100644 index 3eb93bd..0000000 --- a/doc/usage.texi +++ /dev/null @@ -1,39 +0,0 @@ -@node Usage -@unnumbered Usage - -All @ref{Configuration, configuration} is assumed to be placed in -@file{rc/cfg}. Probably you want to deal with multiple server -configurations simultaneously. You place them in corresponding -@file{rc/NAME.cfg} directories and use @url{http://cr.yp.to/redo.html, -redo} default target to create necessary symbolic link of -@file{rc/NAME.cfg} to @file{rc/cfg} and build executable itself. - -@example -$ redo example -# will produce example executable with rc/example.cfg configuration - -$ redo fcgi.example -# will produce fcgi.example executable with rc/fcgi.example.cfg configuration -@end example - -But because you will mostly like to create binary patches to quickly -update already existing binaries, then you can use @file{make-update.sh} -script, that will store newly created binaries in @file{updates/} -directory and make shell-script with the built-in binary patch and -SHA512 checksum checker: - -@example -# First run -$ ./make-update example -$ scp updates/example.old web-server:/path/to/www-server - -$ ./make-update example -$ scp updates/example-update.sh web-server:/tmp -web-server $ /tmp/example-update.sh /path/to/www-server -web-server $ svc -t /var/service/www-server -@end example - -@file{contrib/service} contains @command{daemontools} example run scripts. - -Send @code{SIGINFO} (@code{SIGUSR1} on Linux) signal to get current -daemon's configuration. diff --git a/doc/www.do b/doc/www.do deleted file mode 100644 index 9f0d6c2..0000000 --- a/doc/www.do +++ /dev/null @@ -1,13 +0,0 @@ -redo-ifchange *.texi -html=godlighty.html -rm -f $html/*.html -${MAKEINFO:=makeinfo} --html \ - --set-customization-variable NO_CSS=1 \ - --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 DATE_IN_HEADER=1 \ - --set-customization-variable ASCII_PUNCTUATION=1 \ - --output $html index.texi -find $html -type d -exec chmod 755 {} + -find $html -type f -exec chmod 644 {} +