Write docs for http-service

[yoshuawuyts]

Write docs for http-service.

• inline docs
• doc tests
• readme
• examples

[gruberb]

👋 I happily take this one! Some guidance might be appreciated!

[yoshuawuyts]

@gruberb yay awesome!

So most items already have docs, but we're missing doc tests + readme + examples. A starting point would be the recent Tide refactor to use http-service internally:

• Refactor to use HttpService internally tide#139
• Add external crate http_service_mock, delete local TestBackend tide#142

hopefully this can serve as a starting point, lmk if you have any questions! ✨

[gruberb]

So I started working on it and I am trying to figure out the smallest possible example to create a new http-service and to be able to http-service::serve().

What I came up so far is:

struct Server {
    message: String,
}

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 {
        FutureObj::new(Box::new(
            Ok(self.message)
        ))
    }
}

#[cfg(feature = "hyper")]
fn main() {
    http_service_hyper::serve(Server, "127.0.0.1");
}

Am I on the right track or how is http-service suppose to be used?

[yoshuawuyts]

@gruberb that seems about right. Possibly the mock backend could also be used so input / output can be inspected, but overall it seems pretty reasonable!

Also I'm assuming the cfg is just a placeholder, and not part of the final output right?

[gruberb]

@yoshuawuyts Yeah, just a place holder!

I might need guidance on two places:

1. I want to create a new Server, where message is a Stream of bytes:

struct Server {
    message: StreamObj<'static, Result<Bytes, std::io::Error>>,
}

Now when I Impl the Server, I have actually no idea how to create a StreamObj, nor could I find any docs which would explain it:

impl Server {
    fn new(message: Bytes) {
        Server {
            message: StreamObj::new(Ok(
                message
            ))
        }
    }
}

How can I create a new StreamObj?

2. When I Impl HttpService for Server, I need to find a way to make this thread safe?

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 {
        FutureObj::new(Box::new(
            async move {
                Ok(Response::new(http_service::Body { 
                    stream: StreamObj::new(Box::new(self.message))
                }))
            }
        ))
    }
}

The message for FutureObj::new(... I am getting is:

FutureObj::new(Box::new(
             ^^^^^^^^^^^^^^ `*mut ()` cannot be shared between threads safely

It's kinda hard to find documentation, and I can't spend the full day coding lately, so some help would be good :)

[yoshuawuyts]

@gruberb hmm, is it required for body to be a stream? If not just having it be a Vec<u8> of bytes might be ideal.

If not, could you push a branch somewhere that I could clone to try some stuff out? I don't know the answer either right now, but if I can poke at it I might be able to help.

[gruberb]

@yoshuawuyts Nice, this helped! Got it to work! Will finish up the tests and write the docs. Publish a PR soon!

[yoshuawuyts]

Issue related to StreamObj (it's getting removed) -- rust-lang/futures-rs#1494

[gruberb]

Closed via #19