Skip to content

Commit c2878ab

Browse files
saviorandsaviorand
committed
update the README
1 parent 4af579a commit c2878ab

File tree

4 files changed

+105
-79
lines changed

4 files changed

+105
-79
lines changed

‎README.md‎

Lines changed: 92 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -37,100 +37,117 @@ Lightbug currently has the following features:
3737

3838
### Check Out These Mojo Libraries:
3939

40-
- Bound Logger - [@toasty/stump](https://github.com/thatstoasty/stump)
41-
- Terminal text styling - [@toasty/mog](https://github.com/thatstoasty/mog)
42-
- CLI Library - [@toasty/prism](https://github.com/thatstoasty/prism)
40+
- Logging - [@toasty/stump](https://github.com/thatstoasty/stump)
41+
- CLI and Terminal - [@toasty/prism](https://github.com/thatstoasty/prism), [@toasty/mog](https://github.com/thatstoasty/mog)
4342
- Date/Time - [@mojoto/morrow](https://github.com/mojoto/morrow.mojo) and [@toasty/small-time](https://github.com/thatstoasty/small-time)
4443

4544
<p align="right">(<a href="#readme-top">back to top</a>)</p>
4645

4746
<!-- GETTING STARTED -->
4847
## Getting Started
4948

50-
The only hard dependencies for `lightbug_http` are Mojo and [Git](https://docs.github.com/en/get-started/getting-started-with-git).
51-
Learn how to get up and running with Mojo on the [Modular website](https://www.modular.com/max/mojo). The Docker installation was removed with the changes in Modular CLI. It will be available once Modular provides needed functionality for Docker setups.
49+
The only hard dependency for `lightbug_http` is Mojo.
50+
Learn how to get up and running with Mojo on the [Modular website](https://www.modular.com/max/mojo).
51+
Once you have a Mojo project set up locally,
5252

53-
Once you have Mojo set up locally,
54-
55-
1. Clone the repo
56-
```sh
57-
git clone https://github.com/saviorand/lightbug_http.git
58-
```
59-
2. Switch to the project directory:
60-
```sh
61-
cd lightbug_http
53+
1. Add the `mojo-community` channel to your `mojoproject.toml`, e.g:
54+
```toml
55+
[project]
56+
channels = ["conda-forge", "https://conda.modular.com/max", "https://repo.prefix.dev/mojo-community"]
6257
```
63-
then run:
64-
```sh
65-
magic run mojo lightbug.🔥
58+
2. Add `lightbug_http` as a dependency:
59+
```toml
60+
[dependencies]
61+
lightbug_http = ">=0.1.0"
6662
```
67-
68-
Open `localhost:8080` in your browser. You should see a welcome screen.
69-
70-
Congrats 🥳 You're using Lightbug!
71-
2. Add your handler in `lightbug.🔥` by passing a struct that satisfies the following trait:
63+
3. Run `magic install` at the root of your project, where `mojoproject.toml` is located
64+
4. Lightbug should now be installed as a dependency. You can import all the default imports at once, e.g:
65+
```mojo
66+
from lightbug_http import *
67+
```
68+
or import individual structs and functions, e.g.
69+
```mojo
70+
from lightbug_http.http import HTTPService, HTTPRequest, HTTPResponse, OK, NotFound
71+
```
72+
there are some default handlers you can play with:
73+
```mojo
74+
from lightbug_http.service import Printer # prints request details to console
75+
from lightbug_http.service import Welcome # serves an HTML file with an image (currently requires manually adding files to static folder, details below)
76+
from lightbug_http.service import ExampleRouter # serves /, /first, /second, and /echo routes
77+
```
78+
5. Add your handler in `lightbug.🔥` by passing a struct that satisfies the following trait:
7279
```mojo
7380
trait HTTPService:
7481
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
7582
...
7683
```
77-
For example, to make a `Printer` service that simply prints the request to console:
78-
```mojo
79-
from lightbug_http.http import HTTPService, HTTPRequest, HTTPResponse, OK
80-
from lightbug_http.strings import to_string
81-
82-
@value
83-
struct Printer(HTTPService):
84-
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
85-
var body = req.body_raw
86-
print(to_string(body))
87-
88-
return OK(body)
89-
```
90-
Routing is not in scope for this library, but you can easily set up routes yourself:
84+
For example, to make a `Printer` service that prints some details about the request to console:
9185
```mojo
92-
from lightbug_http.http import HTTPService, HTTPRequest, HTTPResponse, OK
93-
from lightbug_http.strings import to_string
94-
95-
@value
96-
struct ExampleRouter(HTTPService):
97-
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
98-
var body = req.body_raw
99-
var uri = req.uri()
100-
101-
if uri.path() == "/":
102-
print("I'm on the index path!")
103-
if uri.path() == "/first":
104-
print("I'm on /first!")
105-
elif uri.path() == "/second":
106-
print("I'm on /second!")
107-
elif uri.path() == "/echo":
108-
print(to_string(body))
109-
110-
return OK(body)
86+
from lightbug_http import *
87+
88+
@value
89+
struct Printer(HTTPService):
90+
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
91+
var uri = req.uri()
92+
print("Request URI: ", to_string(uri.request_uri()))
93+
94+
var header = req.header
95+
print("Request protocol: ", header.protocol_str())
96+
print("Request method: ", to_string(header.method()))
97+
print("Request Content-Type: ", to_string(header.content_type()))
98+
99+
var body = req.body_raw
100+
print("Request Body: ", to_string(body))
101+
102+
return OK(body)
111103
```
104+
6. Start a server listening on a port with your service like so.
105+
```mojo
106+
fn main() raises:
107+
var server = SysServer()
108+
var handler = Printer()
109+
server.listen_and_serve("0.0.0.0:8080", handler)
110+
```
111+
Feel free to change the settings in `listen_and_serve()` to serve on a particular host and port.
112+
113+
Now send a request `0.0.0.0:8080`. You should see some details about the request printed out to the console.
112114
113-
We plan to add more advanced routing functionality in a future library called `lightbug_api`, see [Roadmap](#roadmap) for more details.
114-
3. Run `magic 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:
115-
```mojo
116-
from lightbug_http import *
115+
Congrats 🥳 You're using Lightbug!
116+
117+
118+
Routing is not in scope for this library, but you can easily set up routes yourself:
119+
```mojo
120+
from lightbug_http import *
121+
122+
@value
123+
struct ExampleRouter(HTTPService):
124+
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
125+
var body = req.body_raw
126+
var uri = req.uri()
127+
128+
if uri.path() == "/":
129+
print("I'm on the index path!")
130+
if uri.path() == "/first":
131+
print("I'm on /first!")
132+
elif uri.path() == "/second":
133+
print("I'm on /second!")
134+
elif uri.path() == "/echo":
135+
print(to_string(body))
136+
137+
return OK(body)
138+
```
139+
140+
We plan to add more advanced routing functionality in a future library called `lightbug_api`, see [Roadmap](#roadmap) for more details.
117141

118-
fn main() raises:
119-
var server = SysServer()
120-
var handler = Welcome()
121-
server.listen_and_serve("0.0.0.0:8080", handler)
122-
```
123-
Feel free to change the settings in `listen_and_serve()` to serve on a particular host and port.
124142

125143
<p align="right">(<a href="#readme-top">back to top</a>)</p>
126144

127145
### Serving static files
128146

129-
The default welcome screen shows an example of how to serve files like images or HTML using Lightbug. Mojo has built-in `open`, `read` and `read_bytes` methods that you can use to read files from e.g. a `static` directory and serve them on a route:
147+
The default welcome screen shows an example of how to serve files like images or HTML using Lightbug. Mojo has built-in `open`, `read` and `read_bytes` methods that you can use to read files and serve them on a route. Assuming you copy an html file and image from the Lightbug repo into a `static` directory at the root of your repo:
130148

131149
```mojo
132-
from lightbug_http.http import HTTPService, HTTPRequest, HTTPResponse, OK, NotFound
133-
from lightbug_http.io.bytes import Bytes
150+
from lightbug_http import *
134151
135152
@value
136153
struct Welcome(HTTPService):
@@ -157,10 +174,8 @@ struct Welcome(HTTPService):
157174
Create a file, e.g `client.mojo` with the following code. Run `magic run mojo client.mojo` to execute the request to a given URL.
158175

159176
```mojo
160-
from lightbug_http.http import HTTPRequest
161-
from lightbug_http.uri import URI
177+
from lightbug_http import *
162178
from lightbug_http.sys.client import MojoClient
163-
from lightbug_http.strings import to_string
164179
165180
fn test_request(inout client: MojoClient) raises -> None:
166181
var uri = URI("http://httpbin.org/status/404")
@@ -185,6 +200,11 @@ fn test_request(inout client: MojoClient) raises -> None:
185200
186201
# print body
187202
print(to_string(response.get_body_bytes()))
203+
204+
205+
fn main() raises -> None:
206+
var client = MojoClient()
207+
test_request(client)
188208
```
189209

190210
Pure Mojo-based client is available by default. This client is also used internally for testing the server.
@@ -195,6 +215,7 @@ By default, Lightbug uses the pure Mojo implementation for networking. To use Py
195215
from lightbug_http.python.server import PythonServer
196216
```
197217
You can then use all the regular server commands in the same way as with the default server.
218+
Note: as of September, 2024, `PythonServer` and `PythonClient` throw a compilation error when starting. There's an open [issue](https://github.com/saviorand/lightbug_http/issues/41) to fix this - contributions welcome!
198219

199220
<!-- ROADMAP -->
200221
## Roadmap

‎client.mojo‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
1-
from lightbug_http.http import HTTPRequest
2-
from lightbug_http.uri import URI
1+
from lightbug_http import *
32
from lightbug_http.sys.client import MojoClient
4-
from lightbug_http.strings import to_string
53

64
fn test_request(inout client: MojoClient) raises -> None:
75
var uri = URI("http://httpbin.org/status/404")
@@ -17,9 +15,6 @@ fn test_request(inout client: MojoClient) raises -> None:
1715
# print status code
1816
print("Response:", response.header.status_code())
1917

20-
# print raw headers
21-
# print("Headers:", response.header.headers())
22-
2318
# print parsed headers (only some are parsed for now)
2419
print("Content-Type:", to_string(response.header.content_type()))
2520
print("Content-Length", response.header.content_length())

‎lightbug_http/__init__.mojo‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
from lightbug_http.http import HTTPRequest, HTTPResponse, OK
1+
from lightbug_http.http import HTTPRequest, HTTPResponse, OK, NotFound
2+
from lightbug_http.uri import URI
23
from lightbug_http.service import HTTPService, Welcome
34
from lightbug_http.sys.server import SysServer
5+
from lightbug_http.strings import to_string
46

57
trait DefaultConstructible:
68
fn __init__(inout self) raises:

‎lightbug_http/service.mojo‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,16 @@ trait HTTPService:
1010
@value
1111
struct Printer(HTTPService):
1212
fn func(self, req: HTTPRequest) raises -> HTTPResponse:
13+
var uri = req.uri()
14+
print("Request URI: ", to_string(uri.request_uri()))
15+
16+
var header = req.header
17+
print("Request protocol: ", header.protocol_str())
18+
print("Request method: ", to_string(header.method()))
19+
print("Request Content-Type: ", to_string(header.content_type()))
20+
1321
var body = req.body_raw
14-
print(to_string(body))
22+
print("Request Body: ", to_string(body))
1523

1624
return OK(body)
1725

0 commit comments

Comments
 (0)