Struct tk_http::server::Encoder

pub struct Encoder<S> { /* fields omitted */ }

This a response writer that you receive in Codec

Methods of this structure ensure that everything you write into a buffer is consistent and valid protocol

Methods

impl<S> Encoder<S>

fn response_continue(&mut self)

Write a 100 (Continue) response.

A server should respond with the 100 status code if it receives a 100-continue expectation.

Panics

When the response is already started. It's expected that your response handler state machine will never call the method twice.

fn status(&mut self, status: Status)

Write status line using Status enum

This puts status line into a buffer immediately. If you don't continue with request it will be sent to the network shortly.

Panics

When status line is already written. It's expected that your request handler state machine will never call the method twice.

When the status code is 100 (Continue). 100 is not allowed as a final status code.

fn custom_status(&mut self, code: u16, reason: &str)

Write custom status line

Panics

When status line is already written. It's expected that your request handler state machine will never call the method twice.

When the status code is 100 (Continue). 100 is not allowed as a final status code.

fn add_header<V: AsRef<[u8]>>(
    &mut self,
    name: &str,
    value: V
) -> Result<(), HeaderError>

Add a header to the message.

Header is written into the output buffer immediately. And is sent as soon as the next loop iteration

Content-Length header must be send using the add_length method and Transfer-Encoding: chunked must be set with the add_chunked method. These two headers are important for the security of HTTP.

Note that there is currently no way to use a transfer encoding other than chunked.

We return Result here to make implementing proxies easier. In the application handler it's okay to unwrap the result and to get a meaningful panic (that is basically an assertion).

Panics

Panics when add_header is called in the wrong state.

fn format_header<D: Display>(
    &mut self,
    name: &str,
    value: D
) -> Result<(), HeaderError>

Same as add_header but allows value to be formatted directly into the buffer

Useful for dates and numeric headers, as well as some strongly typed wrappers

fn add_length(&mut self, n: u64) -> Result<(), HeaderError>

Add a content length to the message.

The Content-Length header is written to the output buffer immediately. It is checked that there are no other body length headers present in the message. When the body is send the length is validated.

Panics

Panics when add_length is called in the wrong state.

fn add_chunked(&mut self) -> Result<(), HeaderError>

Sets the transfer encoding to chunked.

Writes Transfer-Encoding: chunked to the output buffer immediately. It is assured that there is only one body length header is present and the body is written in chunked encoding.

Panics

Panics when add_chunked is called in the wrong state.

fn is_started(&self) -> bool

Returns true if at least status() method has been called

This is mostly useful to find out whether we can build an error page or it's already too late.

fn done_headers(&mut self) -> Result<bool, HeaderError>

Closes the HTTP header and returns true if entity body is expected.

Specifically false is returned when status is 1xx, 204, 304 or in the response to a HEAD request but not if the body has zero-length.

Similarly to add_header() it's fine to unwrap() here, unless you're doing some proxying.

Panics

Panics when the response is in a wrong state.

fn write_body(&mut self, data: &[u8])

Write a chunk of the message body.

Works both for fixed-size body and chunked body.

For the chunked body each chunk is put into the buffer immediately prefixed by chunk size. Empty chunks are ignored.

For both modes chunk is put into the buffer, but is only sent when rotor-stream state machine is reached. So you may put multiple chunks into the buffer quite efficiently.

You may write a body in responses to HEAD requests just like in real requests but the data is not sent to the network. Of course it is more efficient to not construct the message body at all.

Panics

When response is in wrong state. Or there is no headers which determine response body length (either Content-Length or Transfer-Encoding).

fn is_complete(&self) -> bool

Returns true if done() method is already called and everything was okay.

fn done(self) -> EncoderDone<S>

Writes needed finalization data into the buffer and asserts that response is in the appropriate state for that.

The method may be called multiple times.

Panics

When the response is in the wrong state.

fn raw_body(self) -> FutureRawBody<S>

Returns a raw body for zero-copy writing techniques

Note: we don't assert on the format of the body if you're using this interface.

Note 2: RawBody (returned by this future) locks the underlying BiLock, which basically means reading from this socket is not possible while you're writing to the raw body.

Good idea is to use interface like this:

1. Set appropriate content-length
2. Write exactly this number of bytes or exit with error

This is specifically designed for using with sendfile

Panics

This method panics if it's called when headers are not written yet.

fn flush(&mut self) -> Result<(), Error> where
    S: AsyncWrite, 

Flush the data to underlying socket

If the whole buffer could not be flushed it schedules a wakeup of the current task when the the socket is writable.

You can find out how many bytes are left using bytes_buffered() method

fn bytes_buffered(&mut self) -> usize

Returns bytes currently lying in the buffer

It's possible that these bytes are left from the previous request if pipelining is enabled.

Trait Implementations

impl<S> Write for Encoder<S>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl<S: AsyncWrite> AsyncWrite for Encoder<S>

fn shutdown(&mut self) -> Poll<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where
    B: Buf, 

Write a Buf into this value, returning how many bytes were written.