Add documentation about SCGI

This commit is contained in:
Emi Tatsuo 2020-12-05 10:30:13 -05:00
parent ae247312f7
commit 680c04abe4
Signed by: Emi
1 changed files with 110 additions and 3 deletions

View File

@ -2,7 +2,7 @@
//! and advanced Gemini applications on either SCGI or raw Gemini.
//! Originally based on [northstar](, though now far
//! divereged, kochab offers many features to help you build your application without any
//! diverged, kochab offers many features to help you build your application without any
//! of the boilerplate or counterintuitive shenanigans. Kochab centers around it's many
//! feature flags, which let you pick out exactly the features you need to build your
//! library, while leaving out features you don't need to keep your application
@ -22,7 +22,7 @@
//! users can access certain areas of an application. This is primarily configured using
//! the [`Server::ratelimit()`] method.
//! * `servedir` - Adds in utilities for serving files & directories from the disk at
//! * `serve_dir` - Adds in utilities for serving files & directories from the disk at
//! runtime. The easiest way to use this is to pass a [`PathBuf`] to the
//! [`Server::add_route()`] method, which will either serve a directory or a single file.
//! Files and directories can also be served using the methods in the [`util`] module.
@ -68,7 +68,114 @@
//! * `gemini_srv`/`scgi_srv` - Switches between serving content using SCGI and serving
//! content as a raw gemini server. One and only one of these features must be enabled,
//! and compilation will fail if both are enabled. See below for more information.
//! ## Gemini & SCGI Modes
//! **It is highly recommended that you read this section, *especially* if you don't know
//! what SCGI is.**
//! Central to kochab's repertoire is the ability to serve either content either through
//! raw Gemini or through a reverse proxy with SCGI. This can be accomplished easily
//! using a single feature flag. But first:
//! ### What's SCGI and why should I be using it?
//! You're probably familiar with the Gemini protocol, and how servers serve things on it.
//! Gemini is easy to serve and simple to work with. You probably went into this project
//! expecting to serve content directly through the Gemini protocol. So what's this about
//! SCGI, and why should you bother using it?
//! The problem that SCGI solves is that it is very difficult to have multiple servers on
//! one domain with Gemini. For example, if you wanted to serve your blog on `/blog.gmi`,
//! but wanted to have an app running on `/app`, you would most likely have to use SCGI.
//! SCGI has two parts: A main gemini server (called the SCGI client) that handles TLS
//! for incoming connections and either serves some static content, runs some other
//! handler, or passes it off to the SCGI server, which is what you'd be writing. The
//! SCGI server doesn't directly interact with the client, but gets plenty of information
//! about the connection from the server, like what path the server is being served on
//! (like "/app"), the end user's IP, and the certificate fingerprint being used, if
//! applicable.
//! Because SCGI servers don't need to bother with TLS, compiling your app as SCGI will
//! also be fairly faster, since kochab doesn't need to bring in `rustls` or any
//! TLS certificate generation libraries.
//! This doesn't necessarily mean that SCGI is for every app, but if you suspect that a
//! user might ever need to run your app on a path other than the main one, or may want to
//! serve static files alongside your site, I encourage you to seriously consider it.
//! ### But I don't want to bother learning a new protocol ![blobcat-pout]
//! You don't have to! Kochab handles everything about it, thanks to the magic of
//! abstraction! The only thing you have to change are the feature flags in your
//! `Config.toml`. In fact, you could even expose the feature flag so that users can
//! compile your crate as either a Gemini or SCGI server without needing to write any
//! conditional compilation!
//! ### Getting started
//! **Updating your feature flags**
//! By default, Kochab serves content over raw gemini, to make it easier for new users to
//! jump right into using the library. This is done using the on-by-default `gemini_srv`
//! feature flag. To switch to SCGI, we want to switch off `gemini_srv` and switch on
//! `scgi_srv`.
//! ```toml
//! [dependencies.kochab]
//! git = ""
//! branch = "stable"
//! default-features = false
//! features = ["scgi_srv"] # and any other features you might need
//! ```
//! **Testing with a minimal SCGI client**
//! To give your code a run, you'll need a server to handle Gemini requests and pass them
//! off to your SCGI server. There's a few Gemini servers out there with SCGI support,
//! but if you're just interested in giving your code a quick run, I'd recommend
//! mollybrown, which has very good SCGI support and is super easy to set up
//! You can grab a copy of molly brown from [][1].
//! Once you have it, you can find a super simple configuration file [here][2], and then
//! just run
//! ```sh
//! molly-brown -c molly-brown.conf
//! ```
//! Now, when you run your code, you can connect to `localhost`, and molly brown will
//! connect to your SCGI server and forward the response on to your Gemini client.
//! **Rewriting Paths**
//! One important difference about writing code for an SCGI server is that your app might
//! be served on a path that's not the base path. If this happens, you suddenly have a
//! distinction between an absolute link for your app, and an absolute link for the gemini
//! server.
//! For example, if an app that's being served on `/app` has a link to `/path`, this could
//! be either:
//! * Meant to be handled by the app by the route at `/path`, which would be `/app/path`
//! for the parent Gemini server, or
//! * Meant to link to some content on the parent gemini server, at `/path`, which would
//! mean linking to a url your app doesn't control
//! Most of the time, you want to do the first one. Thankfully, Kochab makes rewriting
//! links relative to the base of your app super easy. In most cases, all you need is to
//! add a single line to your Server builder pattern.
//! For more information, see [`Server::set_autorewrite()`].
//! [1]:
//! [2]:
//! [blobcat-pout]: ":blobcat-pout:"
//! <style>
//! img[alt=blobcat-pout] { width: 20px; vertical-align: top; }
//! </style>
#[macro_use] extern crate log;