http-types provides shared types for HTTP operations. It combines a performant, streaming interface with convenient methods for creating headers, urls, and other standard HTTP types. This is part of the http-rs project and powers the tide framework and surf client. Check out the docs or join us on Zulip.

Highlights

This release represents continued support of the http-types 2.x release line due to delays in the development of http-types 3.0.0. This release comes with several convenience features, listed below.

The http-types 3.0 merge window remains open, and you can see the nominated items for the next major version as part of the Semver-Major issue on GitHub.

Changed

• Allowed Request.query() to deserialize into a borrowed Deserialize<'de> rather than just DeserializeOwned. #333
  • This is a looser restriction and is not a breaking change. See serde's documentation on the subject.

Added

• More HTTP Methods from the IANA registry. #332
• Body::chain() for merge multiple Body instances. #342, #346
• AsRef<str> for Version, returning 'static str. #351
• Error::from_debug(), a helper for converting from std::error::Errors. #345
• Error::from_display, a helper for converting from std::error::Errors. #345

Fixed

• Corrected error messages for Content-Encoding and Transfer-Encoding. #354

Docs

• Improved request examples with the url's crate new TryFrom<&str>. #324
• 4xx status codes now have the right descriptions. #341
• Fixed for Content-Encoding and Transfer-Encoding docs. #354

http-types provides shared types for HTTP operations. It combines a performant, streaming interface with convenient methods for creating headers, urls, and other standard HTTP types. This is part of the http-rs project and powers the tide and surf frameworks. Check out the docs or join us on Zulip.

Highlights

This release introduces several new typed headers:

• transfer::TransferEncoding: The form of encoding used to safely transfer the payload body to the user.
• transfer::TE: Client header advertising the transfer encodings the user agent is willing to accept.
• other::RetryAfter: Indicate how long the user agent should wait before making a follow-up request.
• other::Referer: Contains the address of the page making the request.
• content::Accept: Client header advertising which media types the client is able to understand.
• content::ContentType: Indicate the media type of a resource's content.

Most notably is probably the RetryAfter header, which can be used to enable load-shedding on the client. An example of such a middleware has been authored for Tide.

http-types 3.0 merge window opened

This marks the final release of the 2.x release line of http-types. It's been almost a year since our last major release, and we've decided to open up the merge window for http-types 3.0 now that 2.10.0 has shipped. You can see the nominated items for the next major version as part of the Semver-Major issue on GitHub.

Because this is the first major release of http-types we're doing since we moved to our monthly release cadence, we're not entirely sure yet how we'll manage this. Perhaps next month's release may be a beta release. Or we may delay doing a release at all until all items have been merged. We'll have to see, but once 3.0 is out we'll resume the monthly release cadence.

Added

• Add the Retry-After type header #314
• Allow omitting cookie support, with a new "cookies" feature #306
• Add Transfer-Encoding and TE headers #301
• Add other::SourceMap header #278
• Add other::Referer header #277
• Add content::{Accept, ContentType} headers #270

Changed

• Update examples to use TryFrom<str> for Url implementation #294

Internal

• Fix clippy lints #321
• Delete .travis.yml #312
• Refactor media type internals #310
• Make MIME tests conditional on the "fs" feature #307
• Upgrade pin-project-lite to 0.2.0 #299

Features:

• Stabilize support for protocol upgrades on Response #291
• Adds BasicAuth::from_credentials #284
• Adds other::Expect header #266
• Provides a uniform interface for retrieving an optional backtrace from http_types::Error whether or not backtraces are available #258
• Adds a proxy-connection header const #283
• Adds Error::into_inner to retrieve an anyhow Error from a http_types::Error #259

Internal:

• Body Read implementation now will not read beyond the content-length, if one is provided. Previously this logic existed in async-h1, but now is the responsibility of Body #282

This patch adds support for cache::ClearSiteData, content::ContentLocation and implements ToHeaderValues for more string types. This continues our progress on implementing typed headers. We're currently at 50/70 implemented, and expect to be finishing up in the near future. At which point we can start to integrate these into higher-level crates such as tide and surf.

Added

• Implement ToHeaderValues for more string types #279
• Add cache::ClearSiteData header #265
• Add content::ContentLocation header #256, #276

Internal

• CI improvements #275

This patch adds support for auth typed headers, enables our enums to be serialized and deserialized through serde, and fixes a bug in our Method string parser.

Auth

This patch introduces type-safe headers for authentication. The core headers are auth::{Authorization, AuthenticationScheme, WwwAuthenticate} which enable a server to request a client to authenticate, and for the client to construct authentication. However for convenience we've added support for the BasicAuth authentication scheme, making it straight forward to add some authentication to your application.

The plan for typed headers is to enable higher-level middleware to be written for them. As you can see in the example below, while application authors no longer need to deal with correctly parsing and encoding headers it's not exactly convenient yet. We're currently about halfway through implementing encoders and parsers for all known typed headers. And once that's complete it'll enable us to iterate on convenient features and middleware in the tide and surf frameworks.

However for now, here's a simplified example of how to use the new BasicAuth typed headers with the tide server:

use tide::http::auth::{AuthenticationScheme, BasicAuth, WwwAuthenticate};
use tide::http::ensure_eq;
use tide::sessions::{MemoryStore, SessionMiddleware};
use tide::{Request, Response};

// Global variables for the example; don't do this in a production setting
const SECRET: &[u8] = b"shhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh";
const USERNAME: &str = "nori";
const PASSWORD: &str = "ilovefish";
const USER_ID: &str = "12";

// Setup a Tide app with a single endpoint that requires authentication
#[async_std::main]
async fn main() -> Result<(), std::io::Error> {
    tide::log::start();
    let mut app = tide::new();
    app.with(SessionMiddleware::new(MemoryStore::new(), SECRET));
    app.at("/").get(login);
    app.listen("127.0.0.1:8080").await?;
    Ok(())
}

// An endpoint that validates the credentials on a request
// and marks a session as authenticated if they pass
async fn login(mut req: Request<()>) -> tide::Result {
    let session = req.session();

    // Check if we're already logged in
    if let Some(_) = session.get::<String>("user_id") {
        return Ok("Already logged in!".into());
    }

    // Check if credentials are passed; if not request them.
    let auth = match BasicAuth::from_headers(&req)? {
        Some(auth) => auth,
        None => {
            let schema = AuthenticationScheme::Basic;
            let realm = "access the tuna mainframe";
            let auth = WwwAuthenticate::new(schema, realm.into());
            return Ok(Response::builder(401)
                .header(auth.name(), auth.value())
                .build());
        }
    };

    // Validate the username and password. In a real application we'd
    // validate the hashed password from a database. This is an example only.
    ensure_eq!(auth.username(), USERNAME, "unknown username");
    ensure_eq!(auth.password(), PASSWORD, "incorrect password");

    // If validation succeeded, mark the session as validated.
    let session = req.session_mut();
    session.insert("user_id", USER_ID)?;

    // Print a success message
    Ok("Login successful!".into())
}

Added

• Add serde::Deserialize and serde::Serialize impls for Version, StatusCode and Method #262
• Add auth::Authorization #252
• Add auth::AuthenticationScheme #252
• Add auth::BasicAuth #252
• Add auth::WwwAuthenticate #252
• Add auth::ProxyAuthorization #252
• Add auth::ProxyAuthenticate #252

Fixed

• Make Method::parse case insensitive #261

This patch introduces various new typed headers, and a feature flag to disable the async-std dependency.

Added

• Add other::Date header #255
• Add server::Allow #254
• Add content::ContentLength #253
• Add a feature flag for async-std to enable people to disable the dependency #246

This patch introduces various typed headers for content-negotiation, proxying, and makes it easier to work with statuscodes in errors.

Added

• Add contains to HeaderValues. #240
• impl Display for Version #238
• Add content::AcceptEncoding. #232
• Add conditional::Vary #225
• Add conditional::{IfMatch, IfNoneMatch} #224
• Add conditional::{IfModifiedSince, IfUnmodifiedSince, LastModified} #222
• Add proxies::Forwarded header #221
• Add cache::Expires #220
• Add cache::Age header #219
• Added Error::type_name #213

Changed

• Allow Error::set_status to take TryInto<StatusCode> #249
• Enabled Error::new to take TryInto<StatusCode> #216
• Tweak main lib docs #235
• Update headers copy #223

Removed

• Removed "unstable" Client and Server traits #218

Fixed

• Fix typo #243
• Fix error message #237
• Headers: etag: reject invalid characters #233

Internal

• Dont deny warnings during dev #245
• Bump dependencies #242
• CI: only run clippy as part of fmt #239
• Upgrade to infer 0.2.3 #236
• Fix clippy warnings #234
• Fix clippy warning #250
• Run ci on stable as well as nightly #229
• Do not run ci for wasm — async-std 1.6.3 does not compile on wasm arch #228
• Main branch renamed to main #226
• Move TimingAllowOrigin to security submodule #217

This patch introduces various unstable trace typed headers, adds a From<&str> impl for Mime, and includes a minor performance improvement.

Added

• Add trace::ServerTiming as "unstable" #203
• Add From<&str> for Mime #179
• Add trace::AllowOrigin as "unstable" #209

Changed

• Normalize the trace submodule #204

Internal

• Remove an unnecessary String allocation #200