58 lines
4 KiB
Markdown
58 lines
4 KiB
Markdown
```
|
|
*. ,.-*,,..
|
|
.` `. .,-'` ````--*,,,..
|
|
.` ;*` ```''-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.
|
|
|
|
```toml
|
|
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][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
|
|
|
|
[northstar]: https://github.com/panicbit/northstar "Northstar GitHub"
|
|
[examples]: ./examples "Code Examples"
|
|
[Cadey]: https://christine.website/ "Cadey (Christine Dodrill)'s Blog"
|
|
[cadey-gemini]: gemini://cetacean.club/ "Cadey's Capsule on Gemini"
|
|
[maj]: https://tulpa.dev/cadey/maj/ "The maj Git Repository"
|