The following features need to be stabilized before Rocket can compile on stable:

• [x] proc_macro_hygiene (rust-lang/rust#54727)
• [x] associated_consts (rust-lang/rust#29646)
• [x] conservative_impl_trait (rust-lang/rust#34511)
• [x] drop_types_in_const (rust-lang/rust#33156)
• [x] more_io_inner_methods (rust-lang/rust#41519)
• [x] pub_restricted (rust-lang/rust#32409)
• [x] struct_field_attributes (rust-lang/rust#41681)
• [x] use_extern_macros (rust-lang/rust#35896)
• [x] fn_box (rust-lang/rust#28796)
• [x] try_from (rust-lang/rust#33417)

The following dependencies rely on nightly features and must be updated before Rocket can compile on stable:

• [x] pear (https://github.com/SergioBenitez/Pear/commit/333c9bf5e2c516c23b17c7482b410f1448c1b3af)

Update (Feb 07, 2017): Added list of features used by Rocket. Update (Feb 28, 2017): Added lookup_host feature. Update (Mar 21, 2017): pub_restricted was stabilized! Update (Mar 30, 2017): Added never_type feature. Update (Apr 16, 2017): Added concat_idents feature. Update (May 19, 2017): Added struct_field_attributes and more_io_inner_methods features. Update (May 19, 2017): concat_idents is no longer used. Update (May 19, 2017): Added links to tracking issues. Update (May 20, 2017): type_ascription is no longer used. Update (Jun 19, 2017): struct_field_attributes was stabilized! Update (Jun 24, 2017): Added try_trait feature. Update (Jul 1, 2017): more_io_inner_methods was stabilized! Update (Jul 9, 2017): associated_consts was stabilized! Update (Sep 7, 2017): lookup_host is no longer used. Update (Sep 14, 2017): drop_types_in_const was stabilized! Update (Sep 14, 2017): Added decl_macro feature. Update (Mar 26, 2018): conservative_impl_trait, never_type, and i128_type were stabilized! Update (Apr 22, 2018): Added fnbox feature. Update (Apr 26, 2018): never_type stabilization was reverted (rust-lang/rust#50121). Update (May 5, 2018): Swapped macro_reexport for use_extern_macros. Update (Jul 29, 2018): Added crate_visibility_modifier and try_from features. Update (Aug 5, 2018): custom_derive is no longer used. Update (Aug 17, 2018): use_extern_macros was stabilized! Update (Sep 3, 2018): const_fn is no longer used. Update (Sep 26, 2018): Added label_break_value feature. Update (Oct 9, 2018): Removed compiler plugin features (custom_attribute, plugin). Update (Oct 9, 2018): Updated proc_macro features. Update (Mar 9, 2019): try_from was stabilized! Update (Apr 13, 2019): fnbox is no longer used. Update (Jul 9, 2019): never_type is no longer used. Update (Jul 19, 2019): decl_macro is no longer used. Update (Sep 9, 2019): specialization is no longer used. Update (Sep 10, 2019): label_break_value is no longer used. Update (Sep 18, 2019): try_trait is no longer used. Update (Sep 21, 2019): crate_visibility_modifier is no longer used. Update (May 19, 2020): proc_macro_hygiene was stabilized! Update (Jul 16, 2020): proc_macro_diagnostics is no longer used. Update (Jul 16, 2020): proc_macro_span is no longer used. Update (Jul 21, 2020): pear was updated to be stable-compatible.

TODO:

• [x] Safely delete existing socket on startup
• [x] Emit error when both address and port are specified(But what if I want to listen on both tcp and unix sockets?)
• [x] TLS over unix socket

Closes #545

Status

Rocket's master branch is currently fully asynchronous and supports async/await!

Pending

• [ ] #1067 - Remove or replace typed headers (PR: #1535)
• [ ] #1329 - Documentation fixes, additions, improvements.
• [ ] #1070 - Expose APIs for customizing the underlying I/O, instead of being restricted to TCP with optional TLS.
• [ ] Detect blocking I/O in async: it seems the best we can do for now is to document the issues. A "blocking-in-async" lint in clippy or rustc would be much nicer, if feasible, but would occur upstream...someday.
• [x] Miscellaneous small TODOs (tagged as TODO.async) throughout code.
• [x] Response bodies are passed back to hyper using a channel.

Done

• [x] Async I/O everything!
• [x] #1325 - Data reading and connection limits.
• [x] Keep-alive and idle client timeouts
• [x] Handling of blocking database connections.
• [x] Gracefully handle panics with 500. (PR #1491)
• [x] #1066 - Add a Write-like interface for responses, and consideration of AsyncRead vs Stream<Item=Result<Chunk, Error>>
• [x] #180, #1374 - fixing graceful shutdown when using "infinite" responders
• [x] #33 - Server-Sent Events
• [x] #1117 - Asynchronous database pools, or at the very least forward compatibility with them.

Design

The async APIs are based on rust's async/await feature and std::future::Future, running on the tokio (0.2) runtime.

• High-level APIs (routes and catchers):
  • Routes can now be defined as #[get|post|route(...)] async fn(params...) -> R where R is any Responder type. Routes that do not await anything can remain unchanged. #[catch]ers can also be defined as an async fn.
  • Methods on Data now return Futures that must be .awaited. As a consequence, any route that uses Data directly must be async. Routes that use data guards such as Json are not affected by this change.
  • Routes that make their own network requests or other I/O should be async, as it will allow other requests to continue while waiting for the operation.
• Mid and low-level APIs (FromTransformedData and FromData, Fairing, Responder)
  • Several traits are now defined using async-trait, re-exported as #[rocket::async_trait].
  • Data is read asynchronously: DataStream implements tokio::io::AsyncRead instead of Read. Thus, FromTransformedData::transform and From(Transformed)Data::from_data are async fn or return Futures.
  • Response bodies are streamed to the client asynchronously: set_body and related methods expect tokio::io::AsyncRead instead of Read.
    • Consequently, Fairing::on_response and Responder::respond_to are now async fn. This allows Responders and Fairings to access and/or replace the body data.
• The testing APIs have been moved to rocket::local::asynchronous and rocket::local::blocking. The blocking test API is simpler to use, and recommended when possible.
• #[rocket::main], #[rocket::launch], and #[rocket::async_test] have been added to make async fn easily accessible for main() and test().
• Many long-standing bugs with keep-alive, graceful shutdown (#180), performance, and more are fixed or will be easier to fix by using actively-supported versions of libraries.
• Some new functionality will be possible to implement, such as SSE and WebSockets. These will likely not make it into Rocket 0.5. At this point, Rocket should not be missing any APIs necessary to implement SSE "by hand". WebSockets is a bit more complicated, and tracked in #90 .

This branch begins the process of migrating Rocket from using the log crate for diagnostics to using tracing.

The motivation for switching from log to tracing was discussed in detail on issue #21, in particular, in this comment and later. In summary, tracing allows detailed tracking of contexts in programs, including asynchronous ones. This is essentially a structured, machine-readable form of the contexts that Rocket's current logging system conveys through indentation. Additionally, tracing data can be consumed to emit data in a wide variety of formats, and is backward-compatible with libraries that use the log crate.

This branch begins the migration by doing the following:

• [x] Adding a trace module with re-exports of core tracing APIs
• [x] Adding a tracing_subscriber::Layer implementation that performs "Rocket-style" log formatting for tracing spans and events, and setting it as the default unless a tracing subscriber is set by the user
• [x] Replacing all existing uses of the log macros with their tracing equivalents.

Furthermore, I've begun the process of converting the existing logging to more idiomatic tracing. I've added tracing spans to several top-level scopes in Rocket, converted some log messages to structured events, and replaced some existing uses of indentation with tracing spans. Hopefully, this can serve as an example for others to continue the migration and add tracing instrumentation in new code.

When possible, I've tried to keep the logging format as close to Rocket's existing logging. I've made a few tweaks to help communicate more of the structured data that tracing diagnostics record, but the emoji and stuff are all still there. Of course, I am open to making additional changes to the default format if desired.

I've also re-exported some core tracing APIs to try to provide a` batteries-included experience, which seems in keeping with Rocket's philosophy. If other folks like this, we can add more re-exports; if we don't, it's fine to remove them.

Potential future work that this PR unlocks includes:

• [ ] Adding Rocket middleware for adding additional user-provided tracing instrumentation.
• [ ] Adding middleware for integrating with distributed tracing using tracing-opentelemetry and trace propagation headers like b3.
• [ ] Adding middleware for emitting [Server-Timing] headers using tracing data (similar to tide-server-timing).
• [ ] Adding more detailed instrumentation to Rocket's internals.
• [ ] Integrating with error handling (using tracing-error).
• [ ] Ensuring that Rocket's code generation and tracing's #[instrument] attribute work together.

Enjoy, and please let me know if there are any questions!

error[E0609]: no field `lifetimes` on type `&syntax::ast::Generics`
  --> /home/sackery/.cargo/registry/src/github.com-1ecc6299db9ec823/rocket_codegen-0.3.5/src/decorators/derive_form.rs:29:32
   |
29 |                 match generics.lifetimes.len() {
   |                                ^^^^^^^^^

error[E0609]: no field `lifetimes` on type `&syntax::ast::Generics`
  --> /home/sackery/.cargo/registry/src/github.com-1ecc6299db9ec823/rocket_codegen-0.3.5/src/decorators/derive_form.rs:32:49
   |
32 |                         let lifetime = generics.lifetimes[0].lifetime;

Hi. I'm upgrading one of my applications from Rocket 0.4 to 0.5. I have an observation and a feature/change request regarding FromFormField.

There are a good set of provided implementations of FromFormField. There is of course the option to implement the trait by hand. There is also the option to derive it for nested parameters. But I use newtypes heavily to make my program typesafe and clearer internally.

Implementing FromFormField for a newtype wrapper around a small string or integer (or other similar small type) is quite inconvenient. Chiefly, the problem is the need to provide an implementation of from_data. Even if the implementation is no more than read into a string, and feed that to a string parser, the amount of boilerplate is considerable.

Or to put it another way, there is a gap between the very cooked provided implementations, and the very manual direct impl. I think that gap consists of types which are parseable from strings (probably, smallish ones).

I would like a more convenient way to define such a FromFormField impl. As a success criterion, it ought to make it easy to implement FromFormField for any type which is FromStr. (But not all FromStr should be FromFormField, and possibly the FromFormField might be different to the FromStr - that should be up to the type's author.)

I have two suggestions for how to achieve this. You may have a better idea.

1. Have the default from_data read the data to a string, and forward to from_value, rather than erroring. (Probably a smaller data limit would be a good idea.)

2. Some kind of macro to generate a from_data impl.

Of these I think 1 is probably best.

To give you a flavour of what I am looking to improve, here is a fragment from in my proto-Rocket-0.5 branch right now (lightly edited, and it doesn't typecheck right now...):

impl<'i,Id> InstanceAccess<'i,Id>
  where Id: AccessId,
        form::Error: From<Id::Error>
{
  #[throws(form::Error<'i>)]
  fn from_str(s: &'i str) -> Self {
    /* actual code for generating an InstanceAccess from a string elided */
  }
}

impl<'v, Id> FromFormField<'v> for InstanceAccess<'v, Id>
  where Id: AccessId,
        form::Error: From<Id::Error>
{
  fn from_value(field: ValueField<'v>) -> Result<Self, form::Error<'v>> {
    InstanceAccess::from_str(FromFormField::from_value(field)?)?
  }

  fn from_data<'life0, 'async_trait>(
    field: DataField<'v, 'life0>
  ) -> Pin<Box<dyn Future<Output = form::Result<'v, Self>> + Send + 'async_trait>>
  where
    'v: 'async_trait,
   'life0: 'async_trait,
    Self: 'async_trait,
  {
    InstanceAccess::from_str(FromFormField::from_data(field).await?)?
  }
}

Feature Requests

1. Why you believe this feature is necessary.

Go, Rails, Express all have some way of parsing nested attributes easily from forms.

2. A convincing use-case for this feature.

I think it would be pretty nice to have the ability to able to specify a struct like:

#[derive(FromForm]
struct StarterApplication {
  user: User,
  business: Business,
}

#[post("/apply", data="<form>")]
fn post_apply(context: Context, form: StartedApplication) -> Flash<Redirect> {
  //..
}

And based on the dot notation or brackets, allow nested attributes in forms to parse automatically:

<input type="email" name="user[email]" />
<input type="email" name="business[name]" />

or

<input type="email" name="user.email" />
<input type="email" name="business.name" />

Instead I find myself doing this:

#[derive(FromForm, Serialize)]
struct StarterApplication {
    user_email: String,
    user_full_name: String,
//... user fields ...
    business_name: String,
//... business fields ...
}

and manually converting it to the individual structs.

That being said, if there was a way to possibly specify multiple structs on FromForm and get access to the form field name and not just the value, that might also be a viable option? I'm not sure what my options are regardless. Perhaps I'm missing something?

3. Why this feature can't or shouldn't exist outside of Rocket.

It could possibly be an extension of rocket if there was a way to get the values of the fields that come through. I'm not sure that is possible though.

Thanks!!

After updating my nightly (from 03-06) I'm getting this error, any idea how to fix it? error[E0425]: cannot find value rocket_param_id in this scope

This error happens only for my delete handler which is in a macro that's used 11 times, so I get the same error 11 times:

			#[post("/delete/<id>")]
			fn delete(me: Customer, id: i64) -> Res<()> {

The other handlers outside of macros, and even the other handlers inside macros but with only guard args and no url args don't cause any errors. E.g. this one is also inside the same macro but causes no error:

			#[post("/list")]
			fn list(me: Customer) -> Res<Vec<View>> {

Is there any way to perform a "clean" shutdown of Rocket, such that any requests currently being handled can finish (and such that managed state can be cleanly dropped)? I'm assuming right now that pressing ^C just kills the program without any graceful shutdown, since I would expect Rocket to print something to stdout otherwise.

Besides not wanting to have a bad experience for users, I'm primarily concerned with the fact that the program I'm writing is using SQLite and therefore killing it abruptly in the middle of any database mutations is probably a bad idea.

This is an attempt to fix #806 (at least partially).

This transparently handles Range requests for &[u8], Vec<u8>, File and NamedFile, when the total size is known, allowing partial downloads.

It also advertises this feature for the listed types by adding an AcceptRanges header.

The implementation follows the MDN examples and the corresponding RFC, but only supports Single part ranges, which is compliant with the RFC, as a server may choose to ignore or reject any range request.

Multipart ranges would most likely be better implemented as a custom Body variant and would be more complicated. I have no use case for those, which is why I did not bother, but if that would be blocking and someone can provide some directions/suggestion on how to implement those (I am not very familiar with rocket's codebase), I would try to tackle that as well. But I would strongly prefer to do that in a separate PR.

I am looking for some initial feedback on the approach. I did implement it in the corresponding Responder implementations to have access to the Range header of the request and the response as well. It seemed fitting. But it would probably also be possible to just parse the header in the Responder and just store that in the Response or Body and deal with it later in the chain (when writing out the Response for example).

Docs and Tests are completely lacking, also formatting was not working well, cargo fmt changed the whole codebase. So I would appreciate some more comments on what I should provide on those subjects as well.

Thanks for your time :)

First off: let me just say that Rocket is very nice and has been a pleasure to use, kudos!

I looked around the docs and couldn't find any support for serving a set of static files from a directory. This is something that I've seen supported in every web framework I've ever used. As an arbitrary example, here's how it works in Flask. This is a pretty common pattern to serve things like CSS files and JS scripts, so I think it would be useful to have. Obviously one can serve individual files by just having a handler that returns a File, but this seems like generally useful functionality. Ideally one would simply be able to do something like rocket::ignite().mount("/static", StaticFiles(some_path).

Rename heading of content about building documentation to "Building Documentation" and change heading level to three, nesting the content under the heading "Building and Testing". Fixes having two "Documentation" headings at the same level.

The SQLite database settings are passed to rusqlite via

[default.databases.rusqlite]
url = "file:rusqlite?mode=memory&cache=shared"

in Rocket.toml according to the examples.

However, it looks like the url is not used by rusqlite anymore since https://github.com/rusqlite/rusqlite/pull/1248. Specifically, according to the tests in that PR, Connection::open("") now has the same effect as Connection::open("file:dummy.db?mode=memory&cache=shared). In other words, the url is ignored:

    #[test]
    fn test_path() -> Result<()> {
        let tmp = tempfile::tempdir().unwrap();
        let db = Connection::open("")?;
        assert_eq!(Some(""), db.path());
        let db = Connection::open_in_memory()?;
        assert_eq!(Some(""), db.path());
        let db = Connection::open("file:dummy.db?mode=memory&cache=shared")?;
        assert_eq!(Some(""), db.path());
        let path = tmp.path().join("file.db");
        let db = Connection::open(path)?;
        assert!(db.path().map(|p| p.ends_with("file.db")).unwrap_or(false));
        Ok(())
    }

Description

While trying to create a prototype rest api with diesel and postgresql, I've ran into this error when trying to use the ROCKET_DATABASES one-liner variable:

Error: Rocket configuration extraction from provider failed.
   >> invalid type: string "{gaslight={url=\"postgres://introvert:5RFcGn5i45RPjSg7p7TgU56zneWiH69u@localhost/gaslight\"}}", expected a map for key `ROCKET_DATABASES` at line 2 column 18
   >> in Rocket.toml TOML file

If I try to use the other variation of this databases variable, or if I use the one-liner in a normal .env file:

Error: database config error for pool named `gaslight`
   >> missing field `url`
Error: Rocket failed to launch due to failing fairings:
   >> 'gaslight' Database Pool

To Reproduce

Here is the github repo; gaslight.

Environment:

• OS Distribution and Kernel: Arch Linux 6.0.12-arch1-1
• Rocket Version: 0.5.0-rc.2
• Rocket Sync DB Pools Version: 0.1.0-rc.2

Additional context

I'm currently trying to learn how work with rust based apis using rocket, and I'm switching between documentation and an example by TmLev. And don't worry, the posgres user creds are not used on any live services.

Existing Functionality

A clear and concise description of existing functionality and why it is insufficient. Examples:

To provide some context, I've mostly been a TS/JS developer who's used Express style backend frameworks to create backend REST APIs. I'm coming to Rocket after having gone through the Rust book, solving the Rustlings course and hand type all the examples from Rust by example. So, although I'm starting to feel fairly comfortable with the Rust language in general, I'm still struggling with advanced things like lifetimes, interior mutability and reference counting as well as threading and thread safety. But being able to type out the follow along examples like the Pastebin tutorial lets me additively understand concepts and features that are gradually introduced. I believe this would be really helpful for new-ish users of the Rocket framework

Suggested Changes

Follow along tutorials like the Pastebin tutorial for all the major examples in the repo

Alternatives Considered

I've tried to type out the examples from the repo but it's quite confusing since they are not introducing a single feature/concept at a time additively to the project and hence quite difficult to trace the logical flow when faced with the entire project

Additional Context

I can understand that this would be a significantly large addition to the docs but I believe every example added would bring more clarity to the framework and Rust in general. This is because it would also showcase Rust's powers in a real life framework in different scenarios instead of just some synthetic examples.

Existing Functionality

Rocket is a framework using "secure defaults". However, cookies are not marked as secure by default.

The functionality to mark a cookie as secure is there, but when libraries set cookies for you it is nearly impossible to mark it as secure. For example https://github.com/jebrosen/rocket_oauth2/blob/0.5.0-rc.1/src/lib.rs#L693 is not marked as secure and cannot be done in any trivial way.

Suggested Changes

Mark private cookies as secure by default. I.e. add 3 lines of code to: https://github.com/SergioBenitez/Rocket/blob/v0.5.0-rc.2/core/lib/src/cookies.rs#L497

Alternatives Considered

This could probably be done using some proxy like nginx, but it would be very hacky. When not using a proxy it is hard to do when using existing libraries like Rocket OAUTH2.

Additional Context

Options to consider:

• only do so when a secure connection is used
• only make it the default for production builds