4 KiB
*. ,.-*,,..
.` `. .,-'` ````--*,,,..
.` ;*` ```''-o
* ,' __ __ __
`. ,' / /______ _____/ /_ ____ _/ /_
⭐ / //_/ __ \/ ___/ __ \/ __ `/ __ \
/ ,< / /_/ / /__/ / / / /_/ / /_/ /
/_/|_|\____/\___/_/ /_/\__,_/_.___/
kochab
A hybrid Raw/SCGI gemini server library to make manifesting your best ideas as painless as possible
(bold text added for readability)
Kochab is an extension & a fork of the Gemini SDK northstar. Where northstar creates an efficient and flexible foundation for Gemini projects, kochab seeks to be as ergonomic and intuitive as possible, making it possible to get straight into getting your ideas into geminispace, with no worrying about needing to build the tools to get there.
kochab comes with several unique features to make it super easy to make your project happen:
Any kochab project can be compiled either to serve raw Gemini or SCGI with a single feature flag. Little to no conversion of the actual code is necessary, meaning you can do all of your development work in raw Gemini mode and switch to SCGI once you're ready for production.
Additionally, kochab optionally comes with a full user management suite which takes all of the work out of setting up a login and registration system with client certificates. Kochab can completely handle prompting users for certificates, storing user data, allowing users to use passwords to link new certificates, and even registering a specific route as an authenticated route.
Kochab might be the only library that can automatically generate TLS certificates, without needing so much as a single line of code on your part. But, if you need to customize this behavior, kochab even offers several different modes to handle certificate generation, or you can turn it off completely to make a tiny and compact binary.
Despite offering all these features, if you need your library to be tiny, kochab can be tiny. With just the SCGI feature turned on, kochab only has 6 direct dependencies, and a total dependency tree size of just 22 dependencies.
Usage
It is currently only possible to use kochab through it's git repo, although it may wind up on crates.rs someday.
kochab = { git = "https://gitlab.com/Alch_Emi/kochab.git", branch = "stable" }
Once you've got that set up, check out some of our examples to jump right into things, or start learning all the amazing features at your disposal by reading our docs [not yet published, please use cargo doc --features ratelimiting,user_management_advanced,user_management_routes,serve_dir].
Generating a key & certificate
By default, kochab enables the certgen feature, which will automatically generate a certificate for you. All you need to do is run the program once and follow the prompts printed to stdout. You can override this behavior by disabling the feature, or by using the methods in the Builder.
If you want to generate a certificate manually, it's recommended that you temporarily enable the certgen feature to do it, and then disable it once you're done, although you can also use the openssl client tool if you wish
Credit where credit is due
As this is a fork of northstar, naturally a fair amount of our code derives from our upstream, and we'd like to grant a generous thank you to panicbit, and all of their work on the original project.
Kochab also depends on the wonderful gemtext parsing/building library written by Cadey [gemini] as part of the maj ecosystem, which also includes its own gemini server library.
Lastly, we use the :milkyway: emoji from Twemoji as our logo in our docs, which is licensed under CC BY 4.0