Emi
/
kochab
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Made the link rewriting docs *way* better

Browse Source
docs
Emi Tatsuo 2 years ago
parent 9bc1f317c5
commit 7add331e0b
Signed by: Emi
GPG Key ID: 68FAB2E2E6DFC98B
3 changed files with 79 additions and 18 deletions
Show Stats Download Patch File Download Diff File

70
src/lib.rs
Unescape View File

@ -832,17 +832,65 @@ impl Server {
/// Enable or disable autorewrite
///
/// Autorewrite automatically detects links in responses being sent out through kochab
/// and rewrites them to match the base of the script. For example, if the script is
/// mounted on "/app", any links to "/page" would be rewritten as "/app/page". This
/// does nothing when in `gemini_srv` mode.
///
/// **Note:** If you are serving *very long* `text/gemini` files using `serve_dir`,
/// then you should avoid setting this to true. Additionally, if using this option,
/// do not try to rewrite your links using [`Request::rewrite_path`] or
/// [`Response::rewrite_all`], as this will apply the rewrite twice.
///
/// For more information about rewriting, see [`Request::rewrite_path`].
/// Many times, an app will served alongside other apps all on one domain. For
/// example:
/// * `gemini://example.com/gemlog/` might be some static content from a gemlog
/// handled by the gemini server
/// * `gemini://example.com/app/` might be where an SCGI app is hosted
/// * `gemini://example.com/` might be some static landing page linking to both the
/// gemlog and the app
///
/// If the user sent a request to `/app/path` in this case, the app would see it as
/// `/path` automatically, so the app doesn't need to care if it's mounted on `/` or
/// `/app`, because it can handle any request to `/path` the same.
///
/// The problem comes when the app needs to write a link. If an app were to send a
/// link to `/path`, expecting the user to come back with a request to `/path`, it
/// might be surprised to see that the user never arrives, and the user might be
/// surprised to find a `51 Not Found` error page.
///
/// This happens because when the user clicks the link to `/path`, their client takes
/// them to `gemini://example.com/path`. The gemini server doesn't see any apps or
/// files being served on `/path`, so it sends a `NotFound`.
///
/// The app *should* have linked to `/app/path`, but in order to do that, it would
/// need to know that it was mounted at `/app`, and include a bunch of logic to figure
/// out the write path. Thankfully, kochab can take care of this for you.
///
/// There are three main tools at your disposal for link rewriting:
///
/// * [`Server::set_autorewrite()`] is the easiest tool to use, and the one that will
/// work the best for most people. By setting this option on your server, it will
/// automatcially check for any gemini links in it's response before it's sent, and
/// rewrite them to be appropriate relative to the app. In this case, our example
/// app would simply send the link as `/path`, and kochab would catch and rewrite it
/// before it's sent out. For more information about this method, keep reading this
/// method's docs.
/// * [`Response::rewrite_all()`] will attempt to rewrite any links it finds in a
/// single response. This is the method that underlies [`Server::set_autorewrite()`],
/// but by calling it on your responses manually, you can choose exactly what
/// responses are rewritten.
/// * [`Request::rewrite_path()`] will rewrite a single link. This method works best
/// for when you need a lot of precision, like including links that need to be
/// rewritten alongside links that don't, or when you're rewriting links in
/// responses that aren't `text/gemini`.
///
/// All of these methods work on both `scgi_srv` and `gemini_srv` modes, so you can
/// use them regardless of what you plan on compiling your server to, which is
/// recommended if you're planning to offer compilation to either, or if you would
/// like to be able to change later. It's worth noting that while it will *work*, on
/// `gemini_srv` mode, `gemini_srv` servers are *always* mounted at the base path, so
/// this method really won't do anything other than sign off that the link is good.
///
/// If there's a problem with rewriting the URLs, typically because the proxy
/// server/SCGI client being used doesn't correctly implement the SCGI spec, then any
/// `text/gemini` responses bearing an absolute link will be `40 TEMPORARY FAILURE`,
/// and an error will be logged explaining what went wrong.
///
/// For more information about how rewritten paths are calculated, see
/// [`Request::rewrite_path()`].\
/// For more information about what responses are rewritten,
/// see [`Response::rewrite_all()`].
pub fn set_autorewrite(mut self, autorewrite: bool) -> Self {
self.autorewrite = autorewrite;
self

12
src/types/request.rs
Unescape View File

@ -222,8 +222,16 @@ impl Request {
/// fail if unable to infer the correct path. If this is the case, None will be
/// returned. Currently, the SCGI headers checked are:
///
/// * `SCRIPT_PATH` (Used by mollybrown)
/// * `SCRIPT_NAME` (Used by GLV-1.12556)
/// * `SCRIPT_PATH` (Used by [mollybrown] and [stargazer])
/// * `SCRIPT_NAME` (Used by [GLV-1.12556])
///
/// [mollybrown]: https://tildegit.org/solderpunk/molly-brown
/// [stargazer]: https://git.sr.ht/~zethra/stargazer/
/// [GLV-1.12556]: https://github.com/spc476/GLV-1.12556
///
/// For an overview of methods for rewriting links, see [`Server::set_autorewrite()`].
///
/// [`Server::set_autorewrite()`]: crate::Server::set_autorewrite()
pub fn rewrite_path(&self, path: impl AsRef<str>) -> Option<String> {
#[cfg(feature = "scgi_srv")] {
self.script_path.as_ref().map(|base| {

15
src/types/response.rs
Unescape View File

@ -148,9 +148,6 @@ impl Response {
#[cfg_attr(feature="gemini_srv",allow(unused_variables))]
/// Rewrite any links in this response based on the path identified by a request
///
/// For more information about what rewriting a link means, see
/// [`Request::rewrite_path`].
///
/// Currently, this rewrites any links in:
/// * SUCCESS (10) requests with a `text/gemini` MIME
/// * REDIRECT (3X) requests
@ -163,10 +160,18 @@ impl Response {
/// this process, this error will be raised
///
/// If the request does not contain enough information to rewrite a link (in other
/// words, if [`Requet::rewrite_path`] returns [`None`]), then false is returned. In
/// all other cases, this method returns true.
/// words, if [`Request::rewrite_path()`] returns [`None`]), then false is returned.
/// In all other cases, this method returns true.
///
/// Panics if a "text/gemini" response is not UTF-8 formatted
///
/// For an overview of methods for rewriting links, see
/// [`Server::set_autorewrite()`].\
/// For more information about how rewritten paths are calculated, see
/// [`Request::rewrite_path()`].
///
/// [`Server::set_autorewrite()`]: crate::Server::set_autorewrite()
/// [`Request::rewrite_path()`]: crate::Server::set_autorewrite()
pub async fn rewrite_all(&mut self, based_on: &crate::Request) -> std::io::Result<bool> {
#[cfg(feature = "scgi_srv")]
match self.status {

Write Preview
Loading…
Cancel
Save