|
| 1 | +//! Lower-level Server connection API. |
| 2 | +//! |
| 3 | +//! The types in thie module are to provide a lower-level API based around a |
| 4 | +//! single connection. Accepting a connection and binding it with a service |
| 5 | +//! are not handled at this level. This module provides the building blocks to |
| 6 | +//! customize those things externally. |
| 7 | +//! |
| 8 | +//! If don't have need to manage connections yourself, consider using the |
| 9 | +//! higher-level [Server](super) API. |
| 10 | +
|
| 11 | +use std::fmt; |
| 12 | + |
| 13 | +use bytes::Bytes; |
| 14 | +use futures::{Future, Poll, Stream}; |
| 15 | +use tokio_io::{AsyncRead, AsyncWrite}; |
| 16 | + |
| 17 | +use proto; |
| 18 | +use super::{HyperService, Request, Response, Service}; |
| 19 | + |
| 20 | +/// A future binding a connection with a Service. |
| 21 | +/// |
| 22 | +/// Polling this future will drive HTTP forward. |
| 23 | +#[must_use = "futures do nothing unless polled"] |
| 24 | +pub struct Connection<I, S> |
| 25 | +where |
| 26 | + S: HyperService, |
| 27 | + S::ResponseBody: Stream<Error=::Error>, |
| 28 | + <S::ResponseBody as Stream>::Item: AsRef<[u8]>, |
| 29 | +{ |
| 30 | + pub(super) conn: proto::dispatch::Dispatcher< |
| 31 | + proto::dispatch::Server<S>, |
| 32 | + S::ResponseBody, |
| 33 | + I, |
| 34 | + <S::ResponseBody as Stream>::Item, |
| 35 | + proto::ServerTransaction, |
| 36 | + >, |
| 37 | +} |
| 38 | + |
| 39 | +/// Deconstructed parts of a `Connection`. |
| 40 | +/// |
| 41 | +/// This allows taking apart a `Connection` at a later time, in order to |
| 42 | +/// reclaim the IO object, and additional related pieces. |
| 43 | +#[derive(Debug)] |
| 44 | +pub struct Parts<T> { |
| 45 | + /// The original IO object used in the handshake. |
| 46 | + pub io: T, |
| 47 | + /// A buffer of bytes that have been read but not processed as HTTP. |
| 48 | + /// |
| 49 | + /// If the client sent additional bytes after its last request, and |
| 50 | + /// this connection "ended" with an upgrade, the read buffer will contain |
| 51 | + /// those bytes. |
| 52 | + /// |
| 53 | + /// You will want to check for any existing bytes if you plan to continue |
| 54 | + /// communicating on the IO object. |
| 55 | + pub read_buf: Bytes, |
| 56 | + _inner: (), |
| 57 | +} |
| 58 | + |
| 59 | +// ===== impl Connection ===== |
| 60 | + |
| 61 | +impl<I, B, S> Connection<I, S> |
| 62 | +where S: Service<Request = Request, Response = Response<B>, Error = ::Error> + 'static, |
| 63 | + I: AsyncRead + AsyncWrite + 'static, |
| 64 | + B: Stream<Error=::Error> + 'static, |
| 65 | + B::Item: AsRef<[u8]>, |
| 66 | +{ |
| 67 | + /// Disables keep-alive for this connection. |
| 68 | + pub fn disable_keep_alive(&mut self) { |
| 69 | + self.conn.disable_keep_alive() |
| 70 | + } |
| 71 | + |
| 72 | + /// Return the inner IO object, and additional information. |
| 73 | + /// |
| 74 | + /// This should only be called after `poll_without_shutdown` signals |
| 75 | + /// that the connection is "done". Otherwise, it may not have finished |
| 76 | + /// flushing all necessary HTTP bytes. |
| 77 | + pub fn into_parts(self) -> Parts<I> { |
| 78 | + let (io, read_buf) = self.conn.into_inner(); |
| 79 | + Parts { |
| 80 | + io: io, |
| 81 | + read_buf: read_buf, |
| 82 | + _inner: (), |
| 83 | + } |
| 84 | + } |
| 85 | + |
| 86 | + /// Poll the connection for completion, but without calling `shutdown` |
| 87 | + /// on the underlying IO. |
| 88 | + /// |
| 89 | + /// This is useful to allow running a connection while doing an HTTP |
| 90 | + /// upgrade. Once the upgrade is completed, the connection would be "done", |
| 91 | + /// but it is not desired to actally shutdown the IO object. Instead you |
| 92 | + /// would take it back using `into_parts`. |
| 93 | + pub fn poll_without_shutdown(&mut self) -> Poll<(), ::Error> { |
| 94 | + try_ready!(self.conn.poll_without_shutdown()); |
| 95 | + Ok(().into()) |
| 96 | + } |
| 97 | +} |
| 98 | + |
| 99 | +impl<I, B, S> Future for Connection<I, S> |
| 100 | +where S: Service<Request = Request, Response = Response<B>, Error = ::Error> + 'static, |
| 101 | + I: AsyncRead + AsyncWrite + 'static, |
| 102 | + B: Stream<Error=::Error> + 'static, |
| 103 | + B::Item: AsRef<[u8]>, |
| 104 | +{ |
| 105 | + type Item = (); |
| 106 | + type Error = ::Error; |
| 107 | + |
| 108 | + fn poll(&mut self) -> Poll<Self::Item, Self::Error> { |
| 109 | + self.conn.poll() |
| 110 | + } |
| 111 | +} |
| 112 | + |
| 113 | +impl<I, S> fmt::Debug for Connection<I, S> |
| 114 | +where |
| 115 | + S: HyperService, |
| 116 | + S::ResponseBody: Stream<Error=::Error>, |
| 117 | + <S::ResponseBody as Stream>::Item: AsRef<[u8]>, |
| 118 | +{ |
| 119 | + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
| 120 | + f.debug_struct("Connection") |
| 121 | + .finish() |
| 122 | + } |
| 123 | +} |
| 124 | + |
0 commit comments