moleserv 0.1.5

Molerat protocol server library.

Moleserv

Moleserv is a server framework for the Molerat protocol. It features a simple syntax for building complicated servers that conform to the Molerat protocol.

Install

pip install moleserv

Use

Basic example

from moleserv.server import Server

server = Server("127.0.0.1")
    .get("/", get_index)
    .get("/about", get_about)

    .put("/", put_index)
    .put("/login", put_login)

server.listen("key.pem", "cert.pem")

The server class takes in an address and an optional port (the default is 2693)

Adding routes

To add a route to moleserv call the function that is the method you wish to use.

Supported methods are

• get
• put
• del note that the function for del is actually delete since del is reserved in Python.

The function takes in a path and a handler function.

For example, to create a path to serve the index page, you would do this:

server.get("/", index_handler)

Or, to serve the about page;

server.get("/about", about_handler)

The same path can be specified for different methods:

server.get("/", get_index_handler)
      .put("/", put_index_handler)

The handler function

Every route must have a handler function. When a client requests that route, Moleserv will call that function to get the response to send to the client.

A handler function is expected to take in one argument that is the client request, and return one variable that is the response.

Here is an example handler function:

def handle_get_index(req: Request) -> Response:
    return Response(10, "Success", content_type="text/plain", content="hello, world!")

And the corresponding path specifier:

server.get("/", handle_get_index)

Requests

The request class holds all the data from the client's request to the server.

Create a Request

req = Request(data) 

Initializing a Request with data will automatically parse and populate the class.

Request method

req.kind

One of the enum moleserv.request.RequestMethod.

class RequestMethod(Enum):
    GET=0
    PUT=1
    DEL=2

This corresponds to the method used in the request.

Request length

req.length

This refers the content-length of the request. It is used internally to ensure that the entire request is received. It can be used to easily get the encoded length of the req.keys.

Request hash

req.hash

The Request hash is the client-provided ID for the req.keys. It should be a sha256sum of the keys, but there are no guarantees.

Request keys

req.keys

These are the parsed key-values sent by the client. For example, if the request looked like this:

put example.com/login
length:32
hash:02f53083ac99d85db16d2226b370c8137e6d2f4f8a5a52dad84d12d6a9f6f471

username:potat
password:molerat

Then the req.keys would look like this:

req.keys = {
        "username": "potat",
        "password": "molerat"
    }

They can be used to access data sent by the client.

Responses

The Response class holds data that can be encoded into a valid molerat response.

Initializing a Response

res = Response(
        status=10,
        message="Success",
        content_type="text/molerat",
        content="# Hello, world!"
    )

Where

• status is the response code of the Response.
• message is the optional status message of the response.
• content_type is the content MIME Type of the response. The default is text/molerat
• content is the text content to be sent with the response.

For error responses, content is not required. Here is an example of a minimal not-found response:

res = Response(32, "Not found")

Displaying a Response

Calling stringify() on Response will render it as a sendable response.

For example:

print(Response(10, "Success", content="# Hello, world!"))

Would print this:

$ python app.py
10
message:Success	
type:text/molerat	
length:15	
hash:55ae6348e27e47214b28bea4d91d7f21914be30faf77af996859b24a73339230	


# Hello, world!

Starting the server

Once you've added all your routes to the server you can start it by calling server.listen("path/to/keyfile", "path/to/certificate")

Contributing

This repository is mainly hosted at git.trinket.icu/moleserv.git, so email patches to [e-mail] are preferred. However, pull requests to the Github repository are also perfectly acceptable. Also feel free to create issues on the Github repository.