Write docs (#19)
* Add first example, update README * Update README.md * Formatting * Update README.md * Add example to lib.rs * Add main() to examples so it compiles * cargo fmt * Add dev-dependency for http-service-hyper * fmt * fmt * Use `run` instead of `serve` * fmt * Change back to run * Fix dependencies * Fmt, update example * Remove not needed line in docs * Ignore doc code
This commit is contained in:
Bastian Gruber
Yoshua Wuyts
parent
90efbfb36e
commit
1f30e91c4d
|
|
@ -1,4 +1,3 @@
|
|||
<<<<<<< HEAD
|
||||
# Generated by Cargo
|
||||
# will have compiled files and executables
|
||||
/target/
|
||||
|
|
@ -9,8 +8,3 @@ Cargo.lock
|
|||
|
||||
# These are backup files generated by rustfmt
|
||||
**/*.rs.bk
|
||||
=======
|
||||
/target
|
||||
**/*.rs.bk
|
||||
Cargo.lock
|
||||
>>>>>>> Initial commit
|
||||
|
|
|
|||
|
|
@ -14,5 +14,8 @@ members = ["http-service-hyper", "http-service-mock"]
|
|||
bytes = "0.4.12"
|
||||
http = "0.1.17"
|
||||
|
||||
[dev-dependencies]
|
||||
http-service-hyper = { path = "http-service-hyper", version = "0.1.1" }
|
||||
|
||||
[dependencies.futures-preview]
|
||||
version = "0.3.0-alpha.14"
|
||||
|
|
|
|||
117
README.md
117
README.md
|
|
@ -1,13 +1,116 @@
|
|||
# http-service
|
||||
<h1 align="center">http-service</h1>
|
||||
<div align="center">
|
||||
<strong>
|
||||
Types and traits to help you implement your own HTTP server
|
||||
</strong>
|
||||
</div>
|
||||
|
||||
[![build status][1]][2]
|
||||
<br />
|
||||
|
||||
Types and traits giving an interface between low-level http server implementations
|
||||
and services that use them. The interface is based on the `std::futures` API.
|
||||
<div align="center">
|
||||
<!-- Crates version -->
|
||||
<a href="https://crates.io/crates/http-service">
|
||||
<img src="https://img.shields.io/crates/v/http-service.svg?style=flat-square"
|
||||
alt="Crates.io version" />
|
||||
</a>
|
||||
<!-- Build Status -->
|
||||
<a href="https://travis-ci.org/rust-net-web/http-service">
|
||||
<img src="https://img.shields.io/travis/rust-net-web/http-service.svg?style=flat-square"
|
||||
alt="Build Status" />
|
||||
</a>
|
||||
<!-- Downloads -->
|
||||
<a href="https://crates.io/crates/http-service">
|
||||
<img src="https://img.shields.io/crates/d/http-service.svg?style=flat-square"
|
||||
alt="Download" />
|
||||
</a>
|
||||
<!-- docs.rs docs -->
|
||||
<a href="https://docs.rs/http-service/0.1.5/http_service">
|
||||
<img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square"
|
||||
alt="docs.rs docs" />
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
<h3>
|
||||
<a href="https://docs.rs/http-service/0.1.5/http_service/">
|
||||
API Docs
|
||||
</a>
|
||||
<span> | </span>
|
||||
<a href="https://discordapp.com/channels/442252698964721669/474974025454452766">
|
||||
Chat
|
||||
</a>
|
||||
</h3>
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
<sub>Built with ⛵ by <a href="https://github.com/rustasync">The Rust Async Ecosystem WG</a>
|
||||
</div>
|
||||
|
||||
## About
|
||||
The crate `http-service` provides the necessary types and traits to implement your own HTTP Server. It uses `hyper` for the lower level TCP abstraction.
|
||||
|
||||
You can use the workspace member [`http-service-hyper`](https://crates.io/crates/http-service-hyper) to run your HTTP Server via `http_service_hyper::serve(HTTP_SERVICE, ADDRESS);`
|
||||
|
||||
This crate uses the latest [Futures](https://github.com/rust-lang-nursery/futures-rs) preview, and therefore needs to be run on Rust Nightly.
|
||||
|
||||
## Examples
|
||||
|
||||
**Cargo.toml**
|
||||
```
|
||||
[dependencies]
|
||||
http-service = "0.1.5"
|
||||
futures-preview = "0.3.0-alpha.14"
|
||||
|
||||
[dependencies.http-service-hyper]
|
||||
version = "0.1.1"
|
||||
```
|
||||
|
||||
**main.rs**
|
||||
```rust
|
||||
#![feature(futures_api, async_await, await_macro, existential_type)]
|
||||
|
||||
use futures::future::{self, FutureObj};
|
||||
use http_service::{HttpService, Response};
|
||||
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
|
||||
|
||||
struct Server {
|
||||
message: Vec<u8>,
|
||||
}
|
||||
|
||||
impl Server {
|
||||
fn create(message: Vec<u8>) -> Server {
|
||||
Server { message }
|
||||
}
|
||||
|
||||
pub fn run(s: Server) {
|
||||
let a = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
|
||||
http_service_hyper::run(s, a);
|
||||
}
|
||||
}
|
||||
|
||||
impl HttpService for Server {
|
||||
type Connection = ();
|
||||
type ConnectionFuture = future::Ready<Result<(), std::io::Error>>;
|
||||
type Fut = FutureObj<'static, Result<http_service::Response, std::io::Error>>;
|
||||
|
||||
fn connect(&self) -> Self::ConnectionFuture {
|
||||
future::ok(())
|
||||
}
|
||||
|
||||
fn respond(&self, _conn: &mut (), _req: http_service::Request) -> Self::Fut {
|
||||
let message = self.message.clone();
|
||||
FutureObj::new(Box::new(async move {
|
||||
Ok(Response::new(http_service::Body::from(message)))
|
||||
}))
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let s = Server::create(String::from("Hello, World").into_bytes());
|
||||
Server::run(s);
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
[MIT](./LICENSE-MIT) OR [Apache-2.0](./LICENSE-APACHE)
|
||||
|
||||
[1]: https://img.shields.io/travis/rust-net-web/http-service.svg?style=flat-square
|
||||
[2]: https://travis-ci.org/rust-net-web/http-service
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
#![feature(futures_api, async_await, await_macro, existential_type)]
|
||||
|
||||
use futures::future::{self, FutureObj};
|
||||
use http_service::{HttpService, Response};
|
||||
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
|
||||
|
||||
struct Server {
|
||||
message: Vec<u8>,
|
||||
}
|
||||
|
||||
impl Server {
|
||||
fn create(message: Vec<u8>) -> Server {
|
||||
Server { message }
|
||||
}
|
||||
|
||||
pub fn run(s: Server) {
|
||||
let a = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
|
||||
http_service_hyper::run(s, a);
|
||||
}
|
||||
}
|
||||
|
||||
impl HttpService for Server {
|
||||
type Connection = ();
|
||||
type ConnectionFuture = future::Ready<Result<(), std::io::Error>>;
|
||||
type Fut = FutureObj<'static, Result<http_service::Response, std::io::Error>>;
|
||||
|
||||
fn connect(&self) -> Self::ConnectionFuture {
|
||||
future::ok(())
|
||||
}
|
||||
|
||||
fn respond(&self, _conn: &mut (), _req: http_service::Request) -> Self::Fut {
|
||||
let message = self.message.clone();
|
||||
FutureObj::new(Box::new(async move {
|
||||
Ok(Response::new(http_service::Body::from(message)))
|
||||
}))
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let s = Server::create(String::from("Hello, World").into_bytes());
|
||||
Server::run(s);
|
||||
}
|
||||
|
|
@ -13,7 +13,7 @@ version = "0.1.1"
|
|||
|
||||
[dependencies]
|
||||
http = "0.1"
|
||||
http-service = "0.1.5"
|
||||
http-service = { version = "0.1.5", path = ".." }
|
||||
hyper = "0.12.27"
|
||||
|
||||
[dependencies.futures-preview]
|
||||
|
|
|
|||
52
src/lib.rs
52
src/lib.rs
|
|
@ -1,5 +1,57 @@
|
|||
//! Types and traits giving an interface between low-level http server implementations
|
||||
//! and services that use them. The interface is based on the `std::futures` API.
|
||||
//!
|
||||
//! ## Example
|
||||
//! ```no_run, rust, ignore
|
||||
//! #![feature(futures_api, async_await, await_macro, existential_type)]
|
||||
//!
|
||||
//! use futures::{
|
||||
//! future::{self, FutureObj},
|
||||
//! };
|
||||
//! use http_service::{HttpService, Response};
|
||||
//! use std::net::{IpAddr, Ipv4Addr, SocketAddr};
|
||||
//!
|
||||
//! struct Server {
|
||||
//! message: Vec<u8>,
|
||||
//! }
|
||||
//!
|
||||
//! impl Server {
|
||||
//! fn create(message: Vec<u8>) -> Server {
|
||||
//! Server {
|
||||
//! message,
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! pub fn run(s: Server) {
|
||||
//! let a = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
|
||||
//! http_service_hyper::run(s, a);
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! impl HttpService for Server {
|
||||
//! type Connection = ();
|
||||
//! type ConnectionFuture = future::Ready<Result<(), std::io::Error>>;
|
||||
//! type Fut = FutureObj<'static, Result<http_service::Response, std::io::Error>>;
|
||||
//!
|
||||
//! fn connect(&self) -> Self::ConnectionFuture {
|
||||
//! future::ok(())
|
||||
//! }
|
||||
//!
|
||||
//! fn respond(&self, _conn: &mut (), _req: http_service::Request) -> Self::Fut {
|
||||
//! let message = self.message.clone();
|
||||
//! FutureObj::new(Box::new(
|
||||
//! async move {
|
||||
//! Ok(Response::new(http_service::Body::from(message)))
|
||||
//! }
|
||||
//! ))
|
||||
//! }
|
||||
//! }
|
||||
//!
|
||||
//! fn main() {
|
||||
//! let s = Server::create(String::from("Hello, World").into_bytes());
|
||||
//! Server::run(s);
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
#![forbid(future_incompatible, rust_2018_idioms)]
|
||||
#![deny(missing_debug_implementations, nonstandard_style)]
|
||||
|
|
|
|||
Loading…
Reference in New Issue