Discover saviorand/lightbug_http Open Source project

Lightbug

🐝 A Mojo HTTP framework with wings 🔥

Quickstart with Docker

To set up Lightbug in one command:

Get Docker or open the project in Codespaces where Docker is already installed:
Copy the contents of the .mojoenv.example file at the root of this repo into a new file called .mojoenv.

Replace <your_modular_auth_token> with your Modular access token (you can find it here)
Run
```
make lightbug
```

Lightbug will start and listen for requests on http://localhost:8080. Enjoy!

Overview

Lightbug is a simple and sweet HTTP framework for Mojo that builds on best practice from systems programming, such as the Golang FastHTTP and Rust may_minihttp.

This is not production ready yet. We're aiming to keep up with new developments in Mojo, but it might take some time to get to a point when this is safe to use in real-world applications.

Lightbug currently has the following features:

Pure Mojo networking! No dependencies on Python by default
Set up a server to listen on a given host/port
Assign your own custom handler to a route
Craft HTTP requests and responses with built-in primitives
Everything is fully typed, with no def functions used

We're working on support for the following (contributors welcome!):

Better error handling, improved form/multipart and JSON support
Multiple simultaneous connections, parallelization and performance optimizations
WebSockets, HTTP 2.0

The test coverage is also something we're working on.

The plan is to get to a feature set similar to Python frameworks like Starlette, but with better performance.

(back to top)

Getting Started

The only hard dependencies for lightbug_http are Mojo and Git. Learn how to get up and running with Mojo on the Modular website.

Once you have Mojo set up locally,

Clone the repo

git clone https://github.com/saviorand/lightbug_http.git

Switch to the project directory:
```
cd lightbug_http
```
then run:
```
mojo lightbug.🔥
```
Open localhost:8080 in your browser. You should see a welcome screen.

Congrats 🥳 You're using Lightbug!

Add your handler in lightbug.🔥 by passing a struct that satisfies the following trait:

trait HTTPService:
 fn func(self, req: HTTPRequest) raises -> HTTPResponse:
     ...

For example, to make a Printer service that simply prints the request to console:

@value
struct Printer(HTTPService):
   fn func(self, req: HTTPRequest) raises -> HTTPResponse:
      var body = req.body_raw
      print(String(body))

      return OK(body)

Routing is not in scope for this library, but you can easily set up routes yourself:

@value
struct ExampleRouter(HTTPService):
   fn func(self, req: HTTPRequest) raises -> HTTPResponse:
      var body = req.body_raw
      var uri = req.uri()

      if uri.path() == "/":
            print("I'm on the index path!")
      if uri.path() == "/first":
            print("I'm on /first!")
      elif uri.path() == "/second":
            print("I'm on /second!")
      elif uri.path() == "/echo":
            print(String(body))

      return OK(body)

We plan to add routing in a future library called lightbug_api, see Roadmap for more details.

Run mojo lightbug.🔥. This will start up a server listening on localhost:8080. Or, if you prefer to import the server into your own app:
```
from lightbug_http.sys.server import SysServer
from lightbug_http.service import Printer


fn main() raises:
   var server = SysServer()
   var handler = Printer()
   server.listen_and_serve("0.0.0.0:8080", handler)
```
Feel free to change the settings in listen_and_serve() to serve on a particular host and port.

(back to top)

Switching between pure Mojo and Python implementations

By default, Lightbug uses the pure Mojo implementation for networking. To use Python's socket library instead, just import the PythonServer instead of the SysServer with the following line:

from lightbug_http.python.server import PythonServer

You can then use all the regular server commands in the same way as with the default server.

Roadmap

Our vision is to develop three libraries, with lightbug_http (this repo) as a starting point:

lightbug_http - HTTP infrastructure and basic API development
lightbug_api - (coming later in 2024!) Tools to make great APIs fast, with support for OpenAPI spec and domain driven design
lightbug_web - (release date TBD) Full-stack web framework for Mojo, similar to NextJS or SvelteKit

The idea is to get to a point where the entire codebase of a simple modern web application can be written in Mojo.

We don't make any promises, though -- this is just a vision, and whether we get there or not depends on many factors, including the support of the community.

See the open issues and submit your own to help drive the development of Lightbug.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. See CONTRIBUTING.md for more details on how to contribute.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star!