# Moleserv
Moleserv is a server framework for the [*Molerat*](https://molerat.trinket.icu) protocol. It features a simple syntax for building complicated servers that conform to the [Molerat](https://molerat.trinket.icu) protocol.
## Install
```bash
pip install moleserv
```
## Use
### Basic example
```py
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:
```py
server.get("/", index_handler)
```
Or, to serve the about page;
```py
server.get("/about", about_handler)
```
The same path can be specified for different methods:
```py
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:
```py
def handle_get_index(req: Request) -> Response:
return Response(10, "Success", content_type="text/plain", content="hello, world!")
```
And the corresponding path specifier:
```py
server.get("/", handle_get_index)
```
### Requests
The request class holds all the data from the client's request to the server.
#### Create a Request
```py
req = Request(data)
```
Initializing a Request with data will automatically parse and populate the class.
#### Request method
```py
req.kind
```
One of the enum `moleserv.request.RequestMethod`.
```py
class RequestMethod(Enum):
GET=0
PUT=1
DEL=2
```
This corresponds to the method used in the request.
#### Request length
```py
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
```py
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
```py
req.keys
```
These are the parsed key-values sent by the client. For example, if the request looked like this:
```plain
put example.com/login
length:32
hash:02f53083ac99d85db16d2226b370c8137e6d2f4f8a5a52dad84d12d6a9f6f471
username:potat
password:molerat
```
Then the `req.keys` would look like this:
```py
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
```py
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:
```py
res = Response(32, "Not found")
```
#### Displaying a Response
Calling `stringify()` on Response will render it as a sendable response.
For example:
```py
print(Response(10, "Success", content="# Hello, world!"))
```
Would print this:
```bash
$ 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](https://git.trinket.icu/moleserv.git), so email patches to moleserv@git.trinket.icu are preferred. However, pull requests to the Github repository are also perfectly acceptable. Also feel free to create issues on the Github repository.
Raw data
{
"_id": null,
"home_page": "https://molerat.trinket.icu",
"name": "moleserv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "network server library molerat protocol",
"author": "Shav Kinderlehrer",
"author_email": "molerat@git.trinket.icu",
"download_url": "https://files.pythonhosted.org/packages/4e/cf/81dc3606d54694e38a39e48106ac208e8ab421ba2678bef3c165d3448c49/moleserv-0.1.5.tar.gz",
"platform": null,
"description": "# Moleserv\n\nMoleserv is a server framework for the [*Molerat*](https://molerat.trinket.icu) protocol. It features a simple syntax for building complicated servers that conform to the [Molerat](https://molerat.trinket.icu) protocol.\n\n## Install\n\n```bash\npip install moleserv\n```\n\n## Use\n\n### Basic example\n\n```py\nfrom moleserv.server import Server\n\nserver = Server(\"127.0.0.1\")\n .get(\"/\", get_index)\n .get(\"/about\", get_about)\n\n .put(\"/\", put_index)\n .put(\"/login\", put_login)\n\nserver.listen(\"key.pem\", \"cert.pem\")\n```\n\nThe server class takes in an address and an optional port (the default is `2693`)\n\n### Adding routes\n\nTo add a route to `moleserv` call the function that is the method you wish to use.\n\nSupported methods are \n\n- `get`\n- `put`\n- `del` note that the function for `del` is actually `delete` since `del` is reserved in Python.\n\nThe function takes in a path and a handler function.\n\nFor example, to create a path to serve the index page, you would do this:\n\n```py\nserver.get(\"/\", index_handler)\n```\n\nOr, to serve the about page;\n\n```py\nserver.get(\"/about\", about_handler)\n```\n\nThe same path can be specified for different methods:\n\n```py\nserver.get(\"/\", get_index_handler)\n .put(\"/\", put_index_handler)\n```\n\n### The handler function\n\nEvery 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.\n\nA handler function is expected to take in one argument that is the client request, and return one variable that is the response.\n\nHere is an example handler function:\n\n```py\ndef handle_get_index(req: Request) -> Response:\n return Response(10, \"Success\", content_type=\"text/plain\", content=\"hello, world!\")\n```\n\nAnd the corresponding path specifier:\n\n```py\nserver.get(\"/\", handle_get_index)\n```\n\n### Requests\n\nThe request class holds all the data from the client's request to the server.\n\n#### Create a Request\n\n```py\nreq = Request(data) \n```\n\nInitializing a Request with data will automatically parse and populate the class.\n\n#### Request method\n\n```py\nreq.kind\n```\n\nOne of the enum `moleserv.request.RequestMethod`. \n\n```py\nclass RequestMethod(Enum):\n GET=0\n PUT=1\n DEL=2\n```\n\nThis corresponds to the method used in the request.\n\n#### Request length\n\n```py\nreq.length\n```\n\nThis 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`.\n\n#### Request hash\n\n```py\nreq.hash\n```\n\nThe Request hash is the client-provided ID for the `req.keys`. It should be a sha256sum of the keys, but there are no guarantees.\n\n#### Request keys\n\n```py\nreq.keys\n```\n\nThese are the parsed key-values sent by the client. For example, if the request looked like this:\n\n```plain\nput example.com/login\nlength:32\nhash:02f53083ac99d85db16d2226b370c8137e6d2f4f8a5a52dad84d12d6a9f6f471\n\nusername:potat\npassword:molerat\n```\n\nThen the `req.keys` would look like this:\n\n```py\nreq.keys = {\n \"username\": \"potat\",\n \"password\": \"molerat\"\n }\n```\n\nThey can be used to access data sent by the client.\n\n### Responses\n\nThe Response class holds data that can be encoded into a valid `molerat` response.\n\n#### Initializing a Response\n\n```py\nres = Response(\n status=10,\n message=\"Success\",\n content_type=\"text/molerat\",\n content=\"# Hello, world!\"\n )\n```\n\nWhere\n\n- `status` is the response code of the Response.\n- `message` is the optional status message of the response.\n- `content_type` is the content MIME Type of the response. The default is `text/molerat`\n- `content` is the text content to be sent with the response.\n\nFor error responses, content is not required. Here is an example of a minimal not-found response:\n\n```py\nres = Response(32, \"Not found\")\n```\n\n#### Displaying a Response\n\nCalling `stringify()` on Response will render it as a sendable response.\n\nFor example:\n\n```py\nprint(Response(10, \"Success\", content=\"# Hello, world!\"))\n```\n\nWould print this:\n\n```bash\n$ python app.py\n10\nmessage:Success\t\ntype:text/molerat\t\nlength:15\t\nhash:55ae6348e27e47214b28bea4d91d7f21914be30faf77af996859b24a73339230\t\n\n\n# Hello, world!\n```\n\n### Starting the server\n\nOnce you've added all your routes to the server you can start it by calling `server.listen(\"path/to/keyfile\", \"path/to/certificate\")`\n\n## Contributing\n\nThis repository is mainly hosted at [git.trinket.icu/moleserv.git](https://git.trinket.icu/moleserv.git), so email patches to moleserv@git.trinket.icu are preferred. However, pull requests to the Github repository are also perfectly acceptable. Also feel free to create issues on the Github repository.\n",
"bugtrack_url": null,
"license": "0BSD",
"summary": "Molerat protocol server library.",
"version": "0.1.5",
"project_urls": {
"Github": "https://github.com/secondary-smiles/moleserv",
"Homepage": "https://molerat.trinket.icu",
"Source": "https://git.trinket.icu/moleserv.git"
},
"split_keywords": [
"network",
"server",
"library",
"molerat",
"protocol"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bdd082f415e6a1014dedd0213085295df4c498bcb7e2abbfbfdee2b98b0df96f",
"md5": "7567228aa54046c6602434d20d172d58",
"sha256": "0e19e890f21225f55e6decbb29ef2f2a733a7cb212ffe0f4465d2648de9a8f75"
},
"downloads": -1,
"filename": "moleserv-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7567228aa54046c6602434d20d172d58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6900,
"upload_time": "2024-01-19T04:26:45",
"upload_time_iso_8601": "2024-01-19T04:26:45.962632Z",
"url": "https://files.pythonhosted.org/packages/bd/d0/82f415e6a1014dedd0213085295df4c498bcb7e2abbfbfdee2b98b0df96f/moleserv-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4ecf81dc3606d54694e38a39e48106ac208e8ab421ba2678bef3c165d3448c49",
"md5": "09ec28609625dc52460f2fe1255941a5",
"sha256": "b931284c7bd9cab6a00152bae576eab088eb816440bf05a32027ef6a76a2d471"
},
"downloads": -1,
"filename": "moleserv-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "09ec28609625dc52460f2fe1255941a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6223,
"upload_time": "2024-01-19T04:26:47",
"upload_time_iso_8601": "2024-01-19T04:26:47.728891Z",
"url": "https://files.pythonhosted.org/packages/4e/cf/81dc3606d54694e38a39e48106ac208e8ab421ba2678bef3c165d3448c49/moleserv-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-19 04:26:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "secondary-smiles",
"github_project": "moleserv",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "moleserv"
}
JSON
