doc/index.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle godlighty
   4
   5 @copying
   6 Copyright @copyright{} 2021 @email{stargrave@@stargrave.org, Sergey Matveev}
   7 @end copying
   8
   9 @node Top
  10 @top godlighty
  11
  12 @command{godlighty} is highly-customizable HTTP, HTTP/2, HTTPS server
  13 written on pure Go.
  14
  15 Why yet another web-server? Because all others suck even for my simple
  16 ordinary needs: they use hateful OpenSSL, lacks documentation, has
  17 complex configuration format, lack some features, hard to extend with.
  18
  19 @itemize
  20
  21 @item Rather minimalistic pure-Go web-server with few number of
  22 dependencies, producing single statically linked executable. Maximal
  23 reuse of native libraries capabilities.
  24
  25 @item Modern, reliable, secure and fast TLS 1.3 implementation with
  26 ChaCha20-Poly1305, session resumption and GOST cryptography (if built
  27 with @url{http://www.gostls13.cypherpunks.ru/, gostls13}). SNI supported.
  28
  29 @item HTTP/1.1, @url{https://en.wikipedia.org/wiki/HTTP%2F2, HTTP/2}
  30 (only when negotiated during ALPN) and keepalives support. Graceful
  31 shutdowns.
  32
  33 @item @code{gzip} and @url{https://facebook.github.io/zstd/, Zstandard}
  34 compression on-the-fly.
  35
  36 @item @code{Range}, @code{ETag} (based on file/directory's
  37 @code{ctime}), @code{Last-Modified} and corresponding precondition
  38 handlers are fully used.
  39
  40 @item Auto-generated directory listings and
  41 read-only @url{https://en.wikipedia.org/wiki/WebDAV, WebDAV} support.
  42
  43 @item If corresponding @file{.meta4} files are found, then @code{Link}
  44 header is generated automatically to that
  45 @url{http://www.metalinker.org/, Metalink}.
  46
  47 @item Very friendly to @url{http://cr.yp.to/daemontools.html, daemontools}.
  48 Can drop (UID, GID, groups) privileges.
  49
  50 @end itemize
  51
  52 Basically all configuration is done directly inside source code.
  53 Initially @command{godlighty} has basic static files handlers (with
  54 compression, HTTP preconditions are enabled of course). In the example
  55 below there are nearly all default functions.
  56
  57 @verbatim
  58 Hosts["example.com"] = &godlighty.HostCfg{
  59     Root: "/www/example.com",
  60     TLS: &godlighty.TLSCfg{
  61         Cert: "/path/to/example.com.pem",
  62         Key: "/path/to/example.com.key.pem",
  63         CACert: "/path/to/ca.pem",
  64     },
  65     DirList: true,
  66     WebDAV: true,
  67     MIMEs: map[string]string{
  68         ".special": "text/x-special-type",
  69     },
  70 }
  71 @end verbatim
  72
  73 If your keys and certificates are in single file and you use common CA
  74 certificate, then it is trivial to DRY:
  75
  76 @verbatim
  77 var (
  78     Etc = "/whatever"
  79     CACert = path.Join(Etc, "ca.pem")
  80 )
  81
  82 func newTLSCfg(host string) *godlighty.TLSCfg {
  83     return &godlighty.TLSCfg{
  84         Cert:   path.Join(Etc, host+".pem"),
  85         Key:    path.Join(Etc, host+".pem"),
  86         CACert: CACert,
  87     }
  88 }
  89 @end verbatim
  90
  91 But there are hooks that can do anything more. For example if you want
  92 to run CGI script or make a redirection:
  93
  94 @verbatim
  95 HostCfg{
  96     ...,
  97     Hooks: []godlighty.Hook{
  98         func(w http.ResponseWriter, r *http.Request) bool {
  99             if r.URL.Path == "/" {
 100                 http.Redirect(w, r, "//here.we.go/", http.StatusMovedPermanently)
 101                 return true
 102             }
 103             return false
 104         },
 105         func(w http.ResponseWriter, r *http.Request) bool {
 106             cgi.Handler{
 107                 Path: "/usr/local/libexec/git-core/git-http-backend",
 108                 Dir:  "/var/empty",
 109                 Env: []string{
 110                     "GIT_PROJECT_ROOT=" + root,
 111                     "GIT_HTTP_EXPORT_ALL=",
 112                 },
 113             }.ServeHTTP(w, r)
 114             return true
 115         },
 116     },
 117 @end verbatim
 118
 119 You can separate your configuration files and add them through
 120 @code{init()} call:
 121
 122 @verbatim
 123 $ ls rc
 124 blog.stargrave.org.go
 125 ca.cypherpunks.ru.go
 126 cgi.go
 127 cryptoanarchy.ru.go
 128 git.go
 129 go.go
 130 if.mirror.cypherpunks.ru.go
 131 lists.cypherpunks.ru.go
 132 mime.go
 133 static.go
 134 tls.go
 135 [...]
 136
 137 $ cat rc/static
 138 package rc
 139
 140 import "path"
 141
 142 func addStaticCfg(host, root string) {
 143     if !path.IsAbs(root) {
 144         root = path.Join(WWW, root)
 145     }
 146     godlighty.Hosts[host] = &godlighty.HostCfg{
 147         Root: root,
 148         TLS:  newTLSCfg(host),
 149     }
 150 }
 151
 152 func addStaticListedDir(host, root string) {
 153     addStaticCfg(host, root)
 154     godlighty.Hosts[host].DirList = true
 155     godlighty.Hosts[host].WebDAV = true
 156 }
 157
 158 func init() {
 159     [...]
 160     addStaticCfg("paster.stargrave.org", "/storage/paster/pastes")
 161     addStaticCfg("www.godlighty.stargrave.org", "godlighty.stargrave.org")
 162     addStaticCfg("www.nncpgo.org", "nncpgo.org")
 163     addStaticListedDir("www.mds.cypherpunks.ru", "/storage/audiobook/mds")
 164     [...]
 165 }
 166 @end verbatim
 167
 168 It is created exclusively to drive my own websites, but if you are
 169 interested, then @code{git clone git://git.stargrave.org/godlighty.git} it.
 170
 171 @bye