Prepare for 0.8.0 release

Author: mhallin

CHANGELOG.md

@@ -1,6 +1,38 @@
 Change log
 ==========
 
+## [0.8.0] – 2017-06-15
+
+## Breaking changes
+
+* To better comply with the specification, and to avoid weird bugs with very
+  large positive or negative integers, support for `i64` has been completely
+  dropped and replaced with `i32`. `i64` is no longer a valid GraphQL type in
+  Juniper, and `InputValue`/`Value` can only represent 32 bit integers.
+
+  If an incoming integer is out of range for a 32 bit signed integer type, an
+  error will be returned to the client.
+  ([#52](https://github.com/mhallin/juniper/issues/52),
+  [#49](https://github.com/mhallin/juniper/issues/49))
+
+* Serde has been updated to 1.0. If your application depends on an older
+  version, you will need to first update your application before you can upgrade
+  to a more recent Juniper. ([#43](https://github.com/mhallin/juniper/pull/43))
+
+* `rustc_serialize` support has been dropped since this library is now
+  deprecated. ([#51](https://github.com/mhallin/juniper/pull/51))
+
+## New features
+
+* A new `rocket-handlers` feature now includes some tools to use the
+  [Rocket](https://rocket.rs) framework. [A simple
+  example](examples/rocket-server.rs) has been added to the examples folder.
+
+## Bugfixes
+
+* A panic in the parser has been replaced with a proper error
+  ([#44](https://github.com/mhallin/juniper/pull/44))
+
 ## [0.7.0] – 2017-02-26
 
 ### Breaking changes
@@ -293,7 +325,8 @@ using the macros and not deriving `GraphQLType` directly.
 * Macro syntax stability has also been improved. All syntactical edge
   cases of the macros have gotten tests to verify their correctness.
 
-[0.6.3]: https://github.com/mhallin/juniper/compare/0.6.3...0.7.0
+[0.8.0]: https://github.com/mhallin/juniper/compare/0.7.0...0.8.0
+[0.7.0]: https://github.com/mhallin/juniper/compare/0.6.3...0.7.0
 [0.6.3]: https://github.com/mhallin/juniper/compare/0.6.2...0.6.3
 [0.6.2]: https://github.com/mhallin/juniper/compare/0.6.1...0.6.2
 [0.6.1]: https://github.com/mhallin/juniper/compare/0.6.0...0.6.1

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "juniper"
-version = "0.7.0"
+version = "0.8.0"
 authors = ["Magnus Hallin <[email protected]>"]
 description = "GraphQL server library"
 license = "BSD-2-Clause"

README.md

@@ -13,7 +13,7 @@ GraphQL servers in Rust that are type-safe and blazingly fast.
 
 Juniper does not include a web server - instead it provides building blocks to
 make integration with existing servers straightforward. It optionally provides a
-pre-built integration for the [Iron framework][iron].
+pre-built integration for the [Iron][iron] and [Rocket] frameworks.
 
 * [Cargo crate](https://crates.io/crates/juniper)
 * [API Documentation](http://mhallin.github.io/juniper)
@@ -24,15 +24,23 @@ Add Juniper to your Cargo.toml:
 
 ```toml
 [dependencies]
-juniper = "0.7.0"
+juniper = "0.8.0"
 ```
 
 If you want the Iron integration enabled, you need to enable the `iron-handlers`
 feature flag:
 
 ```toml
 [dependencies]
-juniper = { version = "0.7.0", features = ["iron-handlers"] }
+juniper = { version = "0.8.0", features = ["iron-handlers"] }
+```
+
+If you want the Rocket integration enabled, you need to use the nightly Rust
+compiler and enable the `rocket-handlers` feature flag:
+
+```toml
+[dependencies]
+juniper = { version = "0.8.0", features = ["rocket-handlers"] }
 ```
 
 ## Building schemas
@@ -100,7 +108,7 @@ graphql_object!(Human: () |&self| {
 ```
 
 You can find the full example in [src/tests/schema.rs][test_schema_rs],
-including polymorphism with traits and interfaces. For an example of the Iron
+including polymorphism with traits and interfaces. For an example of framework
 integration, see the [examples folder][examples].
 
 ## Features
@@ -120,7 +128,7 @@ Juniper has not reached 1.0 yet, thus some API instability should be expected.
 
 ## 1.0 Roadmap
 
-> Version 0.7.0 probably be re-released as 1.0 to indicate API stability.
+> Version 0.8.0 probably be re-released as 1.0 to indicate API stability.
 
 The road to 1.0 _focuses_ on two aspects: making sure the API hasn't got any
 obvious dead-ends with respect to probable future features, and improving test
@@ -150,3 +158,4 @@ as well.
 [test_schema_rs]: src/tests/schema.rs
 [tokio]: https://github.com/tokio-rs/tokio
 [examples]: examples/
+[Rocket]: https://rocket.rs

src/http.rs

@@ -1,11 +1,19 @@
+//! Utilities for building HTTP endpoints in a library-agnostic manner
+
 use serde::ser;
 use serde::ser::SerializeMap;
 
 use ::{GraphQLError, Value, Variables, GraphQLType, RootNode};
 use ast::InputValue;
 use executor::ExecutionError;
 
-/// The expected structure of the decoded JSON Document for either Post or Get requests.
+/// The expected structure of the decoded JSON document for either POST or GET requests.
+///
+/// For POST, you can use Serde to deserialize the incoming JSON data directly
+/// into this struct - it derives Deserialize for exactly this reason.
+///
+/// For GET, you will need to parse the query string and exctract "query",
+/// "operationName", and "variables" manually.
 #[derive(Deserialize)]
 pub struct GraphQLRequest {
     query: String,
@@ -27,6 +35,7 @@ impl GraphQLRequest {
         }).unwrap_or_default()
     }
 
+    /// Construct a new GraphQL request from parts
     pub fn new(query: String, operation_name: Option<String>, variables: Option<InputValue>) -> GraphQLRequest {
         GraphQLRequest {
             query: query,
@@ -35,6 +44,10 @@ impl GraphQLRequest {
         }
     }
 
+    /// Execute a GraphQL request using the specified schema and context
+    ///
+    /// This is a simple wrapper around the `execute` function exposed at the
+    /// top level of this crate.
     pub fn execute<'a, CtxT, QueryT, MutationT>(
         &'a self,
         root_node: &RootNode<QueryT, MutationT>,
@@ -54,10 +67,18 @@ impl GraphQLRequest {
     }
 }
 
-
+/// Simple wrapper around the result from executing a GraphQL query
+///
+/// This struct implements Serialize, so you can simply serialize this
+/// to JSON and send it over the wire. Use the `is_ok` method to determine
+/// whether to send a 200 or 400 HTTP status code.
 pub struct GraphQLResponse<'a>(Result<(Value, Vec<ExecutionError>), GraphQLError<'a>>);
 
 impl<'a> GraphQLResponse<'a> {
+    /// Was the request successful or not?
+    ///
+    /// Note that there still might be errors in the response even though it's
+    /// considered OK. This is by design in GraphQL.
     pub fn is_ok(&self) -> bool {
         self.0.is_ok()
     }

src/integrations/iron_handlers.rs

@@ -1,4 +1,8 @@
-//! Optional handlers for the Iron framework. Requires the `iron-handlers` feature enabled.
+//! Optional handlers for the [Iron](http://ironframework.io) framework. Requires the `iron-handlers` feature enabled.
+//!
+//! See the [server.rs](https://github.com/mhallin/juniper/blob/master/examples/server.rs)
+//! example for more information on how to use these handlers.
+
 use iron::prelude::*;
 use iron::middleware::Handler;
 use iron::mime::Mime;

src/integrations/rocket_handlers.rs

@@ -1,3 +1,12 @@
+//! Optional helper functions for the [Rocket](https://rocket.rs) framework. Requires the "rocket-handlers" feature enabled.
+//!
+//! The two exposed types in this module are simple wrapper around the
+//! types exposed by the `http` module, but they are better suited for use
+//! in handler functions in the Rocket framework.
+//!
+//! See the [rocket-server.rs](https://github.com/mhallin/juniper/blob/master/examples/rocket-server.rs)
+//! example for how to use these tools.
+
 use std::io::{Cursor, Read};
 use std::error::Error;
 
@@ -17,14 +26,23 @@ use ::http;
 use types::base::GraphQLType;
 use schema::model::RootNode;
 
-pub struct GraphQLResponse(Status, String);
+/// Simple wrapper around an incoming GraphQL request
+///
+/// See the `http` module for more information. This type can be constructed
+/// automatically from both GET and POST routes by implementing the `FromForm`
+/// and `FromData` traits.
 pub struct GraphQLRequest(http::GraphQLRequest);
 
+/// Simple wrapper around the result of executing a GraphQL query
+pub struct GraphQLResponse(Status, String);
+
+/// Generate an HTML page containing GraphiQL
 pub fn graphiql_source(graphql_endpoint_url: &str) -> content::HTML<String> {
     content::HTML(::graphiql::graphiql_source(graphql_endpoint_url))
 }
 
 impl GraphQLRequest {
+    /// Execute an incoming GraphQL query
     pub fn execute<CtxT, QueryT, MutationT>(
         &self,
         root_node: &RootNode<QueryT, MutationT>,

src/lib.rs

@@ -10,13 +10,14 @@ statically verify their queries against a server without actually executing
 them.
 
 This library provides data types and traits to expose Rust types in a GraphQL
-schema, as well as an optional integration into the [Iron framework][2]. It
-tries to keep the number of dynamic operations to a minimum, and give you as the
-schema developer the control of the query execution path.
+schema, as well as an optional integration into the [Iron framework][2] and
+[Rocket]. It tries to keep the number of dynamic operations to a minimum, and
+give you as the schema developer the control of the query execution path.
 
 Juniper only depends on `serde` and `serde_derive` by default, making it
-lightweight and easy to drop into any project. Through the `iron-handlers`
-feature, it also depends on Iron.
+lightweight and easy to drop into any project. If you enable any of the
+optional framework integrations, it will naturally depend on those frameworks
+too.
 
 ## Exposing data types
 
@@ -98,9 +99,11 @@ the [`graphql_object!`][3] macro.
 ## Integrating with Iron
 
 The most obvious usecase is to expose the GraphQL schema over an HTTP endpoint.
-To support this, the library provides an optional and customizable Iron handler.
+To support this, the library provides optional and customizable handlers for
+both Iron and Rocket.
 
-For example, continuing from the schema created above:
+For example, continuing from the schema created above and using Iron to expose
+the schema on an HTTP endpoint supporting both GET and POST requests:
 
 ```rust,no_run
 extern crate iron;
@@ -180,6 +183,7 @@ built-in [GraphiQL][6] handler included.
 [4]: iron_handlers/index.html
 [5]: iron_handlers/struct.GraphQLHandler.html
 [6]: https://github.com/graphql/graphiql
+[Rocket]: https://rocket.rs
 
 */