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

Expand the README

Browse source
This commit is contained in:
Emi Tatsuo 2020-12-11 14:41:29 -05:00
parent 2501c9021a
commit 80198818af
Signed by: Emi
GPG key ID: 68FAB2E2E6DFC98B
1 changed files with 27 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
README.md
View file

@ -10,7 +10,21 @@
``` ```
# kochab # kochab
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. A hybrid Raw/SCGI gemini server library to make
*(**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 # Usage
@ -20,10 +34,22 @@ It is currently only possible to use kochab through it's git repo, although it m
kochab = { git = "https://gitlab.com/Alch_Emi/kochab.git", branch = "stable" } 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 # 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`. 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 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.
[northstar]: https://github.com/panicbit/northstar "Northstar GitHub" [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"