Home

Awesome

Gemeaux: a Python Gemini Server

travis build badge for "main" branch PyPI version of gemeaux PyPI license PyPI pyversions

The Gemini protocol is an ongoing initiative to build a clutter-free content-focused Internet browsing, à la Gopher, but modernized. It focuses on Privacy (TLS + no user tracking) and eliminates the fluff around the modern web: cookies, ads, overweight Javascript apps, browser incompatibilities, etc.

It has been designed for enabling a developer to build a client or a server within a few hours of work. I have been able to serve Gemini static content after two afternoons, so I guess I'm an average developer. But after that, I've tried to improve it, make it more flexible and extensible.

So, here it is: the Gemeaux server.

IMPORTANT NOTE: since this project is still in its earliest stages, it's worth saying that this software IS DEFINITELY NOT READY FOR PRODUCTION — and would probably never will ;o).

Clients

A quick word about Gemini protocol. Since it's a different protocol from HTTP, or Gopher, or FTP, etc., it means that you'll have to drop your beloved Web Browser to access Gemini content. Hopefully, several clients are available.

Download and install a couple of clients, pick one that fits your needs, or if you feel like it, build one yourself, and you'll be ready to spacewalk the Gemini ecosystem.

For development purposes, I'd recommend bollux, a browser made for bash, because it displays helpful debug messages (and it's as fast as you can dream).

Requirements

Gemeaux is built around the standard Python 3.6+ library and syntax. There are no external dependencies.

Automated tests are launched using Python 3.6, 3.7, 3.8 and 3.9, so the internals of Gemeaux are safe with these versions of Python.

You'll also need openssl to generate certificates.

Quickstart

Install via PyPI

To install the latest release of gemeaux package, inside a virtualenv, or in a safe environment, run the following:

pip install gemeaux

Developer mode

git clone https://github.com/brunobord/gemeaux.git
# You may also want to use this source: git@github.com:brunobord/gemeaux.git
cd gemeaux/
pip install -e .

Generate certificates

Since TLS is mandatory, you'll have to generate your own SSL certificate files. Use the following command to generate self-signed certificate files, targeting a localhost/developer mode:

make cert

This command will generate two files: cert.pem and key.pem.

Again, this will probably not be safe for production.

Usage

The "hello world" of this proof of concept would be to serve a directory containing an index.gmi file.

For example, the index.gmi can look like this:

# Hello World!

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

Then you'll create a python file (e.g.: app.py) containing the following:

from gemeaux import App, StaticHandler

if __name__ == "__main__":
    urls = {
        "": StaticHandler(
            static_dir="path/to/your/directory/"
        ),
    }
    app = App(urls)
    app.run()

Note: The static_dir argument can be a relative or an absolute path.

Then you'll run your program using Python 3+:

python app.py

You can then point your client at gemini://localhost/ and you'll see the content of your home page.

By default, the application will listen at port 1965 on your localhost (127.0.0.1) host, and will use the previously generated cert.pem and key.pem files.

In order to open your server to "the world", you can change the --ip option like this:

python app.py --ip 0.0.0.0

BIG WARNING: opening your server to external connections is DEFINITELY NOT A GOOD IDEA, since this software IS NOT PRODUCTION-READY.

You can change the default configuration values using the optional arguments. For more details, run:

python app.py --help

Advanced usage

The urls configuration is at the core of the application workflow. By combining the available Handler and Response classes, you have the ability to create more complex Gemini spaces.

You may read the example application, in the example_app.py file if you want to see an advanced usage of handlers & responses.

Several classes are provided in this library. All classes described below can be imported from the gemeaux module directly, as in from gemeaux import <MyClass>.

Handlers

Most of the time, when working with Handler basic classes, you'll have to implement/override two methods:

StaticHandler

This handler is used for serving a static directory and its subdirectories.

How to instantiate:

StaticHandler(
    static_dir,
    directory_listing=True,
    index_file="index.gmi"
)

Note: If your client is trying to reach a subdirectory like this: gemini://localhost/subdirectory (without the trailing slash), the client will receive a Redirection Response targetting gemini://localhost/subdirectory/ (with the trailing slash).

TemplateHandler

This handler provides methods to render Gemini content, mixing a text template and context variables.

The constructor has no specific arguments, but accepts *args and **kwargs. You'll have to overwrite/override two methods in order to correctly mix the template content with the context variables.

To retrieve the template file, you can overwrite/override the get_template_file() method:

TemplateHandler.get_template_file()

Alternatively, you may assign it a static template_file attribute, like this:

class MyTemplateHandler(TemplateHandler):
    template_file = "/path/to/template.txt"

The template file name doesn't require a specific file extension. By default, TemplateHandler instances will use the string.Template module from the standard library to render content.

Note: we know that this "template engine" is a bit too minimalist for advanced purposes ; but as this project mantra is "no external dependencies". Still, this project is a Python project ; so you can plug your favorite template engine and serve dynamic content the way you want.

Example template:

I am a template file. Refresh me to see what time it is: $datetime

To generate your context variable(s), you'll have to overwrite/override the get_context() method:

class DatetimeTemplateHandler(TemplateHandler):
    template_file = "/path/to/template.txt"

    def get_context(self, *args, **kwargs):
        return {"datetime": datetime.datetime.now()}

This get_context() method should return a dictionary. When accessed, the $datetime variable will be replaced by its value from the context dictionary.

Responses

Response classes are the direct links when it comes to returning content to the client. All responses are inheriting from the gemeaux.responses.Response. Reponses are blocks of text, returned as Python bytes to the client via the communication socket. Responses are composed of two main elements:

Note: If you check with the Gemini project specification, you may see that some response types are missing. They'll eventually be added in a further release.

10: InputResponse

Usage:

InputResponse(prompt="What's your name?")

This response will prompt the user. When the user will answer the question, the client is supposed to send a new request, adding the answer to the prompt at the end of the originating URL. For example:

It's the integrator duty to proceed with the client answer, then.

11: SensitiveInputResponse

Usage:

SensitiveInputResponse(prompt="What's your name?")

Same as for the InputResponse, except that your answer will be hidden on your client interface when you'll type it.

20: SuccessResponse

Usage:

SuccessResponse()

You'll probably never use this response class directly, since it'll return no response body. It'll be your parent class for your custom responses, when the request is successful. See the Custom Responses below.

30: RedirectResponse

Usage:

RedirectResponse(target="gemini://localhost/moon/")

This class will send a Redirect response, with target being the next URL. This default redirection is supposed to be temporary, for example if it follows an application workflow.

31: PermanentRedirectResponse

Usage:

PermanentRedirectResponse(target="gemini://localhost/moon/base/")

Whether the redirection is permanent or temporary, clients will behave alike. But crawlers and search engine spiders will consider the permanent redirections differently, and should remember to crawl the new target and deprecate the previous URL.

50: PermanentFailureResponse

Usage:

PermanentFailureResponse(reason="You forgot to say 'please'")

Your application has failed for a "good" reason and it'll always fail when your user requests this resource this way. The reason argument is optional. If omitted, the message will read 50 PERMANENT FAILURE.

51: NotFoundResponse

Usage:

NotFoundResponse(reason="These are not the droids you are looking for")

The requested resource is not found (its code is 51, because you'll never find what's in the Area 51). The reason argument is optional. If omitted, the message will read 51 NOT FOUND.

54: ProxyRequestRefusedResponse

Usage:

ProxyRequestRefusedResponse()

This response is returned when the server is receiving a query not directly related to its host(name).

The proxy use case

You're building a Gemini server called moonbase. It receives requests for local resources, but you're allowing your server to act as a proxy for the server named lunarstation. It can be another Gemini server or an HTTP(s) server, or Gopher, etc. So if you allow it, you can authorize incoming requests for https://lunarstation/example/resource, fetch this resource by yourself, transcribe it into a regular Gemini Response and return it to your client.

Otherwise, if you don't allow it, simply return the ProxyRequestRefusedResponse as described above.

Note: The proxy feature is not implemented yet in Gemeaux, but it's planned for a future release.

59: BadRequestResponse

Usage:

BadRequestResponse(reason="You've been very naughty, no cake for you")

Return this Bad Request response whenever the request doesn't fulfill the Gemini specs or is wrong in a way or another. The reason argument is optional. If omitted, the response will read: 59: BAD REQUEST.

Custom Response classes

In order to ease development of Gemini websites / applications, Gemeaux is providing a few Response classes to return classic Gemini content.

TextResponse

The text response is composed of a title and a body content. It's one of the most direct way to return Gemini markup. You may use it to return dynamic content.

Here is an example:

from random import randint
from gemeaux import TextResponse
response = TextResponse(
    title="Fancy a game?",
  body=f"Rolled: {randint(1, 6)}\r\nRefresh the page to make another roll."
)

The arguments title and body are both optional. But of course, returning an empty content can be puzzling for your users.

The title will be rendered as # Fancy a game?. The rest of the content (the body variable) will be flushed to the user. Please note that all combinations of \n & \r will be converted into \r\n.

DocumentResponse

Another quick way to return Gemini content is write it down in a text file. You can then return your response to the client as if it was served by a static web server, except that it'll be a Gemini response.

Example:

DocumentResponse(
    full_path="/var/gemini/content/file.gmi",
    root_dir="/var/gemini/content"
)

Please note that both full_path and root_dir arguments are mandatory. The root_dir argument should prevent your application to try to access a file that doesn't belong to the root directory of your static content. You wouldn't like your /etc/passwd file to be revealed using a DocumentResponse instance, would you?

DirectoryListingResponse

One may consider too annoying to make a homepage for a static directory yourself. The DirectoryListingResponse is providing you a way to display the list of the given directory.

Example:

DirectoryListingResponse(
    full_path="/var/gemini/content/moon/base/",
    root_dir="/var/gemini/content"
)

Note: if the provided path is not a directory, or is not part of the root_dirpath, a FileNotFoundError will be raised.

TemplateResponse

When you want your dynamic content to respect some sort of structure, you may want to leverage templates to avoid repeating yourself.

The TemplateResponse class constructor has one mandatory argument: template_file, which is the path to the template file. Then there's a context kwargs, that will be transmitted to the template.

A template file is a text file that respects the String subsitution API described here.

Example template:

Hello, $full_name! Welcome aboard.

Now let's imagine your TemplateResponse class is instantiated like this:

TemplateResponse("/path/to/hello.txt", full_name="Gus Grissom")

When returned to the client as a Response, This will be rendered as:

Hello, Gus Grissom! Welcome aboard.

You can pass as many context variables as you want, but here are some important notes:

  1. For each template variable (like $stuff), you must give it a value.
  2. Basic Python types will be properly rendered, but the stdlib string.Template has no advanced template features: no loops over a list of items, etc. There are plans to make it easier to plug your favorite template engine in the future (in the meantime, you can try to make the mix of your templates and dynamic variables in your Handler class and return a TextResponse yourself).

Known bugs & limitations

This project is mostly for education purposes, although it can possibly be used through a local network, serving Gemini content. There are important steps & bugs to fix before becoming a more solid alternative to other Gemini server software.

What's in the name?

"Gémeaux" is the French word for "Gemini". And incidentally, I was born a Gemini. In French it's pronounced \ʒe.mo\.

Disclaimer: I don't believe in astrology.

Other projects

License

Gemeaux server is distributed as Free Software under the terms of the MIT License. See the contents of the LICENSE file for more details.