Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/7sDream/amiya
experimental middleware-based minimalism async HTTP server framework
https://github.com/7sDream/amiya
Last synced: about 2 months ago
JSON representation
experimental middleware-based minimalism async HTTP server framework
- Host: GitHub
- URL: https://github.com/7sDream/amiya
- Owner: 7sDream
- License: bsd-3-clause-clear
- Created: 2020-07-20T19:10:54.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2021-03-28T06:39:00.000Z (over 3 years ago)
- Last Synced: 2024-07-05T16:31:24.047Z (3 months ago)
- Language: Rust
- Size: 184 KB
- Stars: 22
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Amiya
[![Badge with github icon][github-badge-img]][github-home] [![Badge with document icon][doc-badge-img]][doc-home]
Amiya is a experimental middleware-based minimalism async HTTP server framework,
built up on [`smol-rs`] related asynchronous components.It's currently still working in progress and in a very early alpha stage.
API design may changes, **DO NOT** use it in any condition except for test or study!
## Goal
The goal of this project is try to build a (by importance order):
- Safe, with `#![forbid(unsafe_code)]`
- Async
- Middleware-based
- Minimalism
- Easy to use
- Easy to extendHTTP framework for myself to write simple web services.
Amiya uses [`async-h1`] to parse and process requests, so only HTTP version 1.1 is supported for
now. HTTP 1.0 or 2.0 is not in goal list, at least in the near future.Performance is **NOT** in the list too, after all, Amiya is just a experimental for now, it uses
many heap alloc (Box) and dynamic dispatch (Trait Object) so there may be some performance loss
compare to use [`async-h1`] directly.## Have a Taste
To start a very simple HTTP service that returns `Hello World` to the client in all paths:
```rust
use amiya::m;fn main() {
let app = amiya::new().uses(m!(ctx =>
ctx.resp.set_body(format!("Hello World from: {}", ctx.path()));
));app.listen("[::]:8080").unwrap();
// ... do other things you want ...
// ... Amiya server will not block your thread ...
}
```Amiya has a built-in multi-thread async executor powered by `async-executor` and `async-io`, http server will run
in it. So `Amiya::listen` is just a normal non-async method, and do not block your thread.## Examples
To run examples, run
```bash
cargo run --example # show example list
cargo run --example hello # run hello
```Top level document of crate has [a brief description of concepts][doc-concepts] used in this
framework, I recommend give it a read first, and then check those examples to get a more intuitive
understanding:- Understand onion model of Amiya middleware system: [`examples/middleware.rs`]
- Use a custom type as middleware: [`examples/measurer.rs`]
- Store extra data in context: [`examples/extra.rs`]
- Use `Router` middleware for request diversion: [`examples/router.rs`]
- Parse query string to json value or custom struct: [`examples/query.rs`]
- Parse body(www-form-urlencoded) to json value or custom struct: [`examples/urlencoded.rs`]
- Match part of path as an argument: [`examples/arg.rs`]
- Use another Amiya app as middleware: [`examples/subapp.rs`]
- Stop Amiya server by using `listen` returned signal sender: [`examples/stop.rs`]Most of those example will use builtin executor, see [`example/tokio_executor.rs`] for how to use a custom executor with Amiya.
## License
BSD 3-Clause Clear License, See [`LICENSE`].
[github-badge-img]: https://img.shields.io/badge/Github-7sDream%2Famiya-8da0cb?style=for-the-badge&labelColor=555555&logo=github
[github-home]: https://github.com/7sDream/amiya
[doc-badge-img]: https://img.shields.io/badge/docs-on_docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=read-the-docs
[doc-home]: https://docs.rs/amiya/latest/amiya/
[doc-concepts]: https://docs.rs/amiya/latest/amiya/#concepts
[`smol-rs`]: https://github.com/smol-rs
[`async-h1`]: https://github.com/http-rs/async-h1
[`examples/hello.rs`]: https://github.com/7sDream/amiya/blob/master/examples/hello.rs
[`examples/middleware.rs`]: https://github.com/7sDream/amiya/blob/master/examples/middleware.rs
[`examples/measurer.rs`]: https://github.com/7sDream/amiya/blob/master/examples/measurer.rs
[`examples/extra.rs`]: https://github.com/7sDream/amiya/blob/master/examples/extra.rs
[`examples/query.rs`]: https://github.com/7sDream/amiya/blob/master/examples/query.rs
[`examples/urlencoded.rs`]: https://github.com/7sDream/amiya/blob/master/examples/urlencoded.rs
[`examples/router.rs`]: https://github.com/7sDream/amiya/blob/master/examples/router.rs
[`examples/arg.rs`]: https://github.com/7sDream/amiya/blob/master/examples/arg.rs
[`examples/subapp.rs`]: https://github.com/7sDream/amiya/blob/master/examples/subapp.rs
[`examples/stop.rs`]: https://github.com/7sDream/amiya/blob/master/examples/stop.rs
[`example/tokio_executor.rs`]: https://github.com/7sDream/amiya/blob/master/examples/tokio_executor.rs
[`LICENSE`]: https://github.com/7sDream/amiya/blob/master/LICENSE