<labelid="sidebar-toggle"class="icon-button"for="sidebar-toggle-anchor"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="../print.html"title="Print this book"aria-label="Print this book">
<iid="print-button"class="fa fa-print"></i>
</a>
</div>
</div>
<divid="search-wrapper"class="hidden">
<formid="searchbar-outer"class="searchbar-outer">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p><ahref="https://spec.graphql.org/October2021#sec-Subscription">GraphQL subscriptions</a> are a way to push data from a server to clients requesting real-time messages from a server. <ahref="https://spec.graphql.org/October2021#sec-Subscription">Subscriptions</a> are similar to <ahref="https://spec.graphql.org/October2021#sec-Query">queries</a> in that they specify a set of fields to be delivered to a client, but instead of immediately returning a single answer a result is sent every time a particular event happens on a server.</p>
<p>In order to execute <ahref="https://spec.graphql.org/October2021#sec-Subscription">subscriptions</a> in <ahref="https://docs.rs/juniper">Juniper</a>, we need a coordinator (spawning long-lived connections) and a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> with <ahref="https://spec.graphql.org/October2021#sec-Language.Fields">fields</a> resolving into a <ahref="https://docs.rs/futures/latest/futures/stream/trait.Stream.html"><code>Stream</code></a> of elements which will then be returned to a client. The <ahref="https://docs.rs/juniper_subscriptions"><code>juniper_subscriptions</code> crate</a> provides a default implementation of these abstractions.</p>
<p>The <ahref="https://spec.graphql.org/October2021#sel-FAHTRJCAACC3EhsX">subscription root</a> is just a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a>, similar to the <ahref="https://spec.graphql.org/October2021#sel-FAHTRFCAACChCtpG">query root</a> and <ahref="https://spec.graphql.org/October2021#sel-FAHTRHCAACCuE9yD">mutations root</a> that we define for operations in our <ahref="https://spec.graphql.org/October2021#sec-Schema">GraphQL schema</a>. For <ahref="https://spec.graphql.org/October2021#sec-Subscription">subscriptions</a> all fields should be <code>async</code> and return a <ahref="https://docs.rs/futures/latest/futures/stream/trait.Stream.html"><code>Stream</code></a> of some <ahref="https://spec.graphql.org/October2021#sec-Types">GraphQL type</a> values, rather than direct values.</p>
<p><ahref="https://spec.graphql.org/October2021#sec-Subscription">GraphQL subscriptions</a> require a bit more resources than regular <ahref="https://spec.graphql.org/October2021#sec-Query">queries</a> and provide a great vector for <ahref="https://en.wikipedia.org/wiki/Denial-of-service_attack">DoS attacks</a>. This can can bring down a server easily if not handled correctly. The <ahref="https://docs.rs/juniper/0.16.0/juniper/trait.SubscriptionCoordinator.html"><code>SubscriptionCoordinator</code> trait</a> provides coordination logic to enable functionality like <ahref="https://en.wikipedia.org/wiki/Denial-of-service_attack">DoS attacks</a> mitigation and resource limits.</p>
<p>The <ahref="https://docs.rs/juniper/0.16.0/juniper/trait.SubscriptionCoordinator.html"><code>SubscriptionCoordinator</code></a> contains the <ahref="https://spec.graphql.org/October2021#sec-Schema">schema</a> and can keep track of opened connections, handle <ahref="https://spec.graphql.org/October2021#sec-Subscription">subscription</a> start and end, and maintain a global ID for each <ahref="https://spec.graphql.org/October2021#sec-Subscription">subscription</a>. Each time a connection is established, the <ahref="https://docs.rs/juniper/0.16.0/juniper/trait.SubscriptionCoordinator.html"><code>SubscriptionCoordinator</code></a> spawns a [32], which handles a single connection, providing resolver logic for a client stream as well as reconnection and shutdown logic.</p>
<p>While we can implement <ahref="https://docs.rs/juniper/0.16.0/juniper/trait.SubscriptionCoordinator.html"><code>SubscriptionCoordinator</code></a> ourselves, <ahref="https://docs.rs/juniper">Juniper</a> contains a simple and generic implementation called <ahref="https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Coordinator.html"><code>Coordinator</code></a>. The <code>subscribe</code> method returns a <ahref="https://doc.rust-lang.org/stable/std/future/trait.Future.html"><code>Future</code></a> resolving into a <code>Result<Connection, GraphQLError></code>, where <ahref="https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Connection.html"><code>Connection</code></a> is a <ahref="https://docs.rs/futures/latest/futures/stream/trait.Stream.html"><code>Stream</code></a> of <ahref="https://spec.graphql.org/October2021#sec-Values">values</a> returned by the operation, and a <ahref="https://docs.rs/juniper/0.16.0/juniper/enum.GraphQLError.html"><code>GraphQLError</code></a> is the error when the <ahref="https://spec.graphql.org/October2021#sec-Subscription">subscription operation</a> fails.</p>
<p>For information about serving <ahref="https://spec.graphql.org/October2021#sec-Subscription">GraphQL subscriptions</a> over <ahref="https://en.wikipedia.org/wiki/WebSocket">WebSocket</a>, see the <ahref="../serve/index.html#websocket">"Serving" chapter</a>.</p>
