1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
// SPDX-FileCopyrightText: 2026 Slatian <baschdel@disroot.org>
//
// SPDX-License-Identifier: AGPL-3.0-or-later
//! # Admin Experience of lib-humus
//!
//! This document is mainly an implementation guide, but also tries to be a bare minimum guide for admins who come across a lib-humus application.
//!
//! ## What is admin experience?
//!
//! You may know User Experience which makes things more enjoyable and consistent for users. When writing rust code you may also know Developer Experience which makes things more enjoyable and consistent on the development side. Admin Experience is … making things more enjoyable and consistent for Admins.
//!
//! Since lib-humus is a non trivial and configurable frontend part it not only interacts with application developers, but also with their administrators, this guide makes sure that admins have a consistent experience when interacting with an application that builds on lib-humus.
//!
//! ## Logging
//!
//! lib-humus uses the [log] crate to communicate errors and warnings, if no other logging sytem in planned please set up an [`env_logger`](https://docs.rs/env_logger/latest/env_logger/). Its verbosity can be controlled through the `RUST_LOG` environment variable.
//!
//! You should do this as the first thing in your main function (even before parsing cli args):
//! ```ignore
//! // Initalize logger:
//! env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
//! ```
//!
//! ## Command line options
//!
//! lib-humus needs some options that should be easily settable from the outside. For (sub)commands that spawn a server process that uses lib humus please add the following options:
//! * `--listen-on <socket_addr>` parse this as a [SocketAddr][core::net::SocketAddr] and open your server socket on.
//! * `--template-location <path>`, allows overriding the default template location. Pass it to [HumusEngineLoader::cli_template_location][crate::HumusEngineLoader::cli_template_location].
//! * `--static-location <path>`, when set it should override path where static files are served from.
//! * `--extra-config <path>`, allows overriding the default path ot the `extra.toml` template configuration. Pass it to [HumusEngineLoader::cli_extra_config_location][crate::HumusEngineLoader::cli_extra_config_location].
//!
//! Use a [PathBuf][std::path::PathBuf] when reading file paths.
//!
//! ## Static files
//!
//! The directory `static/` in the template directory is reserved for static files so that no reverse proxy is needed to serve static content by default.
//!
//! The command line option `--static-location <path>` must ovveride this path.
//!
//! As a developer do not assume that your application is in control of serving static files, the administrator should be able to point their webserver at the static content and have it just work!
//!
//! Provide `robots.txt` with some good defaults.
//!
//! Example snippet of how serving the static directory could be implemented using `tower_http::services::ServeDir`:
//!
//! ```rust,ignore
//! let static_file_directory = args.static_location
//! .unwrap_or(humus_engine_loader.base_dir().join("/static"));
//! log::info!("Static files will be served from: {static_file_directory:?}");
//!
//! let app = Router::new()
//! /* put your routes here */
//! .fallback_service(
//! ServeDir::new(static_file_directory)
//! .fallback(your_not_found_handler),
//! )
//! ```
//!
//! ## Provide documentation
//!
//! Even though lib-humus takes care of a lot of frontend work please document the following:
//!
//! * Parameters for the reverse proxy:
//! * A restrictive [content security policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) that can be applied in a reverse proxy. (Keep in mind that browsers have special treatment for `localhost` when testing)
//! * Should cache headers be set, if yes what makes sense on which paths.
//! * Templating parameters:
//! * Which API formats do you provide? (The [JsonOnlyApiFormat][crate::templating::JsonOnlyApiFormat] only provides the `json` format)
//! * Which views are available and what do they provide in the `data` variable.
//! * Additional variables you are setting in [HumusView::initalize_template_context][crate::HumusView::initalize_template_context].
//! * Additional functions you've made available to the template.
//! * Additional functionality you've registred with the fluent templates in the language engine.
//! * What do your default templates expect in the `extra.toml` file? (The easiest way to do this is to put comments in your default extra.toml)
//!