Trillium 0.2.0

[jbr]

Summary

Trillium 0.2.0 represents a number of breaking changes to trillium's API that hopefully will provide a better long term basis for iterative improvement. In particular, this release primarily serves to move trillium away from http-types, in order to make development more flexible and specialized. There is no intention to support the use of trillium-http's types outside of trillium, unlike http-types, which intends to be a general purpose library.

Previously, trillium-http had been using a fork of http-types, but that meant that trillium was still exposing (and thus supporting) a substantial amount of superfluous code that in the form of typed headers. This represented a maintenance liability with little upside. Trillium's approach will be to implement header parsers as needed, in subcrates that use the specific headers, and only when driven by use cases trillium supports.

Additionally, trillium-http@0.2.0 introduces a new header map implementation and response body type and renames several types from http-types. These types provide performance gains over the http-types equivalents, as determined by local http benchmarks.

General note:

This release introduces a number of type renamings and signature changes, and I would like to communicate that changes like this will be rare and decreasing over time. I appreciate the cost that unnecessary changes have to application authors, but at this early stage of development, it's preferable to break things sooner than later.

Continued support and patches for 0.1.x

As a matter of practice to set expectations for future versions of trillium, the 0.1.x branch will be maintained and all bugfixes backported for at least a year from today.

Specific Changes

trillium 0.2.0:

• Swap order of arguments to conn_try and conn_unwrap
• Conn::with_header takes two arguments instead of a http_types Header
• No longer depend on http-types headers, see below changes for trillium-http

trillium-http 0.2.0:

• renamed trillium_http::Conn::response_headers → trillium_http::Conn::response_headers_mut, added trillium_http::Conn::response_headers which does not require &mut, added trillium_http::Conn::request_headers_mut for parity
• all Headers interfaces have been rewritten and are likely to have changed. In particular:
  • Headers no longer are Index
  • Headers::get returns None if there are more than one header value for that header. To retrieve all of the potential values, use Headers::get_values
  • KnownHeaderNames are the preferred way to describe a HeaderName
  • Extensions renamed to StateSet to match the docs
• StatusCode renamed to Status
• New Body type. Importantly and intentionally, this new Body does is not From<&str>, but only From<String> and From<&'static str> — If you need to make a new body from a borrowed string, you must clone it.

trillium-testing 0.3.1:

• assert_headers! no longer requires a &mut conn because of the above change to trillium-http

trillium-conn-id 0.2.0:

In order to accept KnownHeaderNames, the following changes have been made:

• with_request_header(Option<&'static str>) has been replaced with with_request_header(impl Into<HeaderName<'static>>) and without_request_header()
• with_response_header(Option<&'static str>) has been replaced with with_response_header(impl Into<HeaderName<'static>>) and without_response_header()

Migration

with_header((name, value)) → with_header(name, value)

This is the most prominent breaking change, and is highly likely to impact your trillium application. Any circumstance that previously was conn.with_header((x, y)) should now become conn.with_header(x, y), eliminating the extra parentheses.

/// trillium 0.1.x
fn main() {
    trillium_smol::run(|conn: trillium::Conn| async move {
        conn.with_header(("content-type", "application/json"))
            .ok(r#"{ "some": "json" }"#)
    })
}

becomes

/// trillium 0.2
fn main() {
    trillium_smol::run(|conn: trillium::Conn| async move {
        conn.with_header("content-type", "application/json")
            .ok(r#"{ "some": "json" }"#)
    })
}

or, for a small performance gain on every request:

```rust
/// trillium 0.2
fn main() {
    trillium_smol::run(|conn: trillium::Conn| async move {
        conn.with_header(trillium::KnownHeaderName::ContentType, "application/json")
            .ok(r#"{ "some": "json" }"#)
    })
}

conn_unwrap(conn, option) → conn_unwrap(option, conn) and conn_try(conn, result) → conn_unwrap(result, conn)

This is a straightforward argument swap, as suggested by @mathiversen here in a discussion

---

This discussion was created from the release Trillium 0.2.0.