An ergonomic and elegant framework for creating Gemini servers and SCGI apps without needless bloat
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Emi Tatsuo caf8e3ee50
continuous-integration/drone/push Build is passing Details
Add in drone configuration with basic testing
2 years ago
examples Add a whole bunch of comments to the examples 3 years ago
public Rebrand as kochab 3 years ago
src Add missing page 3 years ago
.drone.yml Add in drone configuration with basic testing 2 years ago
.gemgit Add .gemgit 3 years ago
.gitignore Added ./data to .gitignore 3 years ago
CHANGELOG.md Rebrand as kochab 3 years ago
Cargo.toml Update rustls 3 years ago
LICENSE.md Add licenses 3 years ago
LICENSE_NORTHSTAR.md Add licenses 3 years ago
README.md I really wrote half a sentence and committed it, huh? 3 years ago
stargazer.ini Actually swap out the stargazer conf 3 years ago

README.md

      *.          ,.-*,,..
    .`  `.   .,-'`       ````--*,,,..
  .`      ;*`                       ```''-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