From 6aed455f03270b6daadc8771c428e1144e265556 Mon Sep 17 00:00:00 2001 From: Magnus Hallin Date: Thu, 15 Jun 2017 16:53:27 +0200 Subject: [PATCH] Prepare for 0.8.0 release --- CHANGELOG.md | 35 ++++++++++++++++++++++++++++- Cargo.toml | 2 +- README.md | 19 +++++++++++----- src/http.rs | 25 +++++++++++++++++++-- src/integrations/iron_handlers.rs | 6 ++++- src/integrations/rocket_handlers.rs | 20 ++++++++++++++++- src/lib.rs | 18 +++++++++------ 7 files changed, 107 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc0ef968..88905370 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/Cargo.toml b/Cargo.toml index c8bef915..1e166b81 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "juniper" -version = "0.7.0" +version = "0.8.0" authors = ["Magnus Hallin "] description = "GraphQL server library" license = "BSD-2-Clause" diff --git a/README.md b/README.md index bc701211..47c929da 100644 --- a/README.md +++ b/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,7 +24,7 @@ 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` @@ -32,7 +32,15 @@ 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 diff --git a/src/http.rs b/src/http.rs index 9649ff7f..ad87b0b7 100644 --- a/src/http.rs +++ b/src/http.rs @@ -1,3 +1,5 @@ +//! Utilities for building HTTP endpoints in a library-agnostic manner + use serde::ser; use serde::ser::SerializeMap; @@ -5,7 +7,13 @@ 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, variables: Option) -> 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, @@ -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), 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() } diff --git a/src/integrations/iron_handlers.rs b/src/integrations/iron_handlers.rs index c2f327c5..97567aa5 100644 --- a/src/integrations/iron_handlers.rs +++ b/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; diff --git a/src/integrations/rocket_handlers.rs b/src/integrations/rocket_handlers.rs index c1aa5adf..b7e97f77 100644 --- a/src/integrations/rocket_handlers.rs +++ b/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 { content::HTML(::graphiql::graphiql_source(graphql_endpoint_url)) } impl GraphQLRequest { + /// Execute an incoming GraphQL query pub fn execute( &self, root_node: &RootNode, diff --git a/src/lib.rs b/src/lib.rs index 156fea00..daffddeb 100644 --- a/src/lib.rs +++ b/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 */