Cleanup docs and comments for pending v3.4.0 release

Author: wravery

PEGTL

@@ -47,7 +47,7 @@ The easiest way to get all of these and to build `cppgraphqlgen` in one step is
 [microsoft/vcpkg](https://github.com/microsoft/vcpkg). To install with vcpkg, make sure you've pulled the latest version
 and then run `vcpkg install cppgraphqlgen` (or `cppgraphqlgen:x64-windows`, `cppgraphqlgen:x86-windows-static`, etc.
 depending on your platform). To install just the dependencies and work in a clone of this repo, you'll need some subset
-of `vcpkg install pegtl boost-program-options boost-filesystem rapidjson gtest`. It works for Windows, Linux, and Mac,
+of `vcpkg install pegtl boost-program-options rapidjson gtest`. It works for Windows, Linux, and Mac,
 but if you want to try building for another platform (e.g. Android or iOS), you'll need to do more of this manually.
 
 Manual installation will work best if you clone the GitHub repos for each of the dependencies and follow the installation
@@ -67,9 +67,9 @@ means you need to include an acknowledgement along with the license text.
 
 ### graphqlpeg
 
-- GraphQL parsing: [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL) release 3.0.0,
+- GraphQL parsing: [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL) release 3.1.1,
 which is part of [The Art of C++](https://taocpp.github.io/) library collection. I've added this as a sub-module, so you
-do not need to install this separately. If you already have 3.0.0 installed where CMake can find it, it will use that
+do not need to install this separately. If you already have 3.1.1 installed where CMake can find it, it will use that
 instead of the sub-module and avoid installing another copy of PEGTL.
 
 ### graphqlservice
@@ -87,11 +87,6 @@ do that.
 
 I'm using [Boost](https://www.boost.org/doc/libs/1_69_0/more/getting_started/index.html) for `schemagen`:
 
-- C++17 std::filesystem support on Unix:
-[Boost.Filesystem](https://www.boost.org/doc/libs/1_69_0/libs/filesystem/doc/index.htm). Most of the default C++
-compilers on Linux still have `std::filesystem` from C++17 in an experimental directory and require an extra
-library. The standard just adopted the Boost library, so on Unix systems I have an `#ifdef` which redirects back to
-it for the time being.
 - Command line handling: [Boost.Program_options](https://www.boost.org/doc/libs/1_69_0/doc/html/program_options.html).
 Run `schemagen -?` to get a list of options. Many of the files in the [samples](samples/) directory were generated
 with `schemagen`, you can look at [samples/CMakeLists.txt](samples/CMakeLists.txt) for a few examples of how to call it:
@@ -108,6 +103,7 @@ Command line options:
   --header-dir arg       Target path for the <prefix>Schema.h header file
   --no-stubs             Generate abstract classes without stub implementations
   --separate-files       Generate separate files for each of the types
+  --no-introspection     Do not generate support for Introspection
 ```
 
 I've tested this with several versions of Boost going back to 1.65.0. I expect it will work fine with most versions of

README.md

@@ -1 +1 @@
-3.3.0
+3.4.0

cmake/version.txt

@@ -11,11 +11,36 @@ passes it to every `getField` method as the first parameter.
 
 The `graphql::service::FieldParams` struct is declared in [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
 ```cpp
-// Pass a common bundle of parameters to all of the generated Object::getField accessors in a SelectionSet
+// Resolvers may be called in multiple different Operation contexts.
+enum class ResolverContext
+{
+	// Resolving a Query operation.
+	Query,
+
+	// Resolving a Mutation operation.
+	Mutation,
+
+	// Adding a Subscription. If you need to prepare to send events for this Subsciption
+	// (e.g. registering an event sink of your own), this is a chance to do that.
+	NotifySubscribe,
+
+	// Resolving a Subscription event.
+	Subscription,
+
+	// Removing a Subscription. If there are no more Subscriptions registered this is an
+	// opportunity to release resources which are no longer needed.
+	NotifyUnsubscribe,
+};
+
+// Pass a common bundle of parameters to all of the generated Object::getField accessors in a
+// SelectionSet
 struct SelectionSetParams
 {
+	// Context for this selection set.
+	const ResolverContext resolverContext;
+
 	// The lifetime of each of these borrowed references is guaranteed until the future returned
-	// by the accessor is resolved or destroyed. They are owned by the OperationData shared pointer. 
+	// by the accessor is resolved or destroyed. They are owned by the OperationData shared pointer.
 	const std::shared_ptr<RequestState>& state;
 	const response::Value& operationDirectives;
 	const response::Value& fragmentDefinitionDirectives;
@@ -25,19 +50,32 @@ struct SelectionSetParams
 	// you'll need to explicitly copy them into other instances of response::Value.
 	const response::Value& fragmentSpreadDirectives;
 	const response::Value& inlineFragmentDirectives;
+
+	// Field error path to this selection set.
+	std::optional<field_path> errorPath;
+
+	// Async launch policy for sub-field resolvers.
+	const std::launch launch = std::launch::deferred;
 };
 
 // Pass a common bundle of parameters to all of the generated Object::getField accessors.
 struct FieldParams : SelectionSetParams
 {
-	explicit FieldParams(const SelectionSetParams& selectionSetParams, response::Value&& directives);
+	GRAPHQLSERVICE_EXPORT explicit FieldParams(
+		SelectionSetParams&& selectionSetParams, response::Value&& directives);
 
-	// Each field owns its own field-specific directives. Once the accessor returns it will be destroyed,
-	// but you can move it into another instance of response::Value to keep it alive longer.
+	// Each field owns its own field-specific directives. Once the accessor returns it will be
+	// destroyed, but you can move it into another instance of response::Value to keep it alive
+	// longer.
 	response::Value fieldDirectives;
 };
 ```
 
+### Resolver Context
+
+The `SelectionSetParams::resolverContext` enum member informs the `getField`
+accessors about what type of operation is being resolved.
+
 ### Request State
 
 The `SelectionSetParams::state` member is a reference to the
@@ -75,7 +113,29 @@ or `fragmentDefinitionDirectives` because those are kept alive until the
 passed by `const` reference, the reference should always be valid as long as
 there's a pending result from the `getField` call.
 
+### Error Path
+
+The `SelectionSetParams::errorPath` member should be considered an opaque
+implementation detail by client code. It automatically propagates through the
+field resolvers, and if there is a schema exception or one of the `getField`
+accessors throws another exception derived from `std::exception`, the
+`graphqlservice` library will automatically add the resulting path to the error
+report, accoring to the [spec](http://spec.graphql.org/June2018/#sec-Errors).
+
+### Launch Policy
+
+The `graphqlservice` library uses the `SelectionSetParams::launch` parameter to
+determine how it should handle async resolvers in the same selection set or
+elements in the same list. It is passed from the top-most `resolve`, `deliver`,
+or async `subscribe`/`unsubscribe` call. The `getField` accessors get a copy of
+this member in their `FieldParams` argument, and they may change their own
+behavior based on that, but they cannot alter the launch policy which
+`graphqlservice` uses for the resolvers themselves.
+
 ## Related Documents
 
 1. The `getField` methods are discussed in more detail in [resolvers.md](./resolvers.md).
-2. Built-in and custom `directives` are discussed in [directives.md](./directives.md).
+2. Built-in and custom `directives` are discussed in [directives.md](./directives.md).
+3. Subscription resolvers get called up to 3 times depending on which
+`subscribe`/`unsubscribe` overrides you call. See [subscriptions.md](./subscriptions.md)
+for more details.

doc/fieldparams.md

@@ -19,9 +19,9 @@ the functions in [JSONResponse.h](../include/JSONResponse.h):
 ```cpp
 namespace graphql::response {
 
-std::string toJSON(Value&& response);
+JSONRESPONSE_EXPORT std::string toJSON(Value&& response);
 
-Value parseJSON(const std::string& json);
+JSONRESPONSE_EXPORT Value parseJSON(const std::string& json);
 
 } /* namespace graphql::response */
 ```

doc/json.md

@@ -4,11 +4,11 @@
 
 As mentioned in the [README](../README.md), `cppgraphqlgen` uses the
 [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL)
-release 3.0.0, which is part of [The Art of C++](https://taocpp.github.io/)
+release 3.1.1, which is part of [The Art of C++](https://taocpp.github.io/)
 library collection. I've added this as a sub-module, so you do not need to
-install this separately. If you already have 3.0.0 installed where CMake can
+install this separately. If you already have 3.1.1 installed where CMake can
 find it, it will use that instead of the sub-module and avoid installing
-another copy of PEGTL. _Note: PEGTL 3.0.0 is currently at pre-release._
+another copy of PEGTL.
 
 It uses the [contrib/parse_tree.hpp](../PEGTL/include/tao/pegtl/contrib/parse_tree.hpp)
 module to build an AST automatically while parsing the document. The AST and
@@ -33,13 +33,24 @@ for hardcoded documents.
 
 The UDL is used throughout the sample unit tests and in `schemagen` for the
 hard-coded introspection schema. It will be useful for additional unit tests
-against your own custom schema.
+against your own custom schema. The UDL 
 
 At runtime, you will probably call `parseString` most often to handle dynamic
 queries. If you have persisted queries saved to the file system or you are
 using a snapshot/[Approval Testing](https://approvaltests.com/) strategy you
 might also use `parseFile` to parse queries saved to text files.
 
+When parsing an executable document with `parseString`, `parseFile`, or the
+UDL, the parser will try a subset of the grammar first which does not accept
+schema definitions, and if that fails it will try the full grammar as a
+fallback so that the validation step can check for documents with an invalid
+mix of executable and schema definitions.
+
+There are `parseSchemaString` and `parseSchemaFile` functions which do the
+opposite, but unless you are building additional tooling on top of the
+`graphqlpeg` library, you will probably not need them. They have only been used
+by `schemagen` in this project.
+
 ## Encoding
 
 The document must use a UTF-8 encoding. If you need to handle documents in

doc/parsing.md

@@ -7,7 +7,7 @@ As the comment in
 responses are not technically JSON-specific, although that is probably the most
 common way of representing them. These are the primitive types that may be
 represented in GraphQL, as of the
-[June 2018 spec](https://facebook.github.io/graphql/June2018/#sec-Serialization-Format):
+[June 2018 spec](http://spec.graphql.org/June2018/#sec-Serialization-Format):
 
 ```c++
 enum class Type : uint8_t

doc/responses.md

@@ -13,8 +13,13 @@ the subscriptions to those listeners.
 Subscriptions are created or removed by calling the `Request::subscribe`
 and `Request::unsubscribe` methods in [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
 ```cpp
-SubscriptionKey subscribe(SubscriptionParams&& params, SubscriptionCallback&& callback);
-void unsubscribe(SubscriptionKey key);
+GRAPHQLSERVICE_EXPORT SubscriptionKey subscribe(
+	SubscriptionParams&& params, SubscriptionCallback&& callback);
+GRAPHQLSERVICE_EXPORT std::future<SubscriptionKey> subscribe(
+	std::launch launch, SubscriptionParams&& params, SubscriptionCallback&& callback);
+
+GRAPHQLSERVICE_EXPORT void unsubscribe(SubscriptionKey key);
+GRAPHQLSERVICE_EXPORT std::future<void> unsubscribe(std::launch launch, SubscriptionKey key);
 ```
 You need to fill in a `SubscriptionParams` struct with the [parsed](./parsing.md)
 query and any other relevant operation parameters:
@@ -37,6 +42,23 @@ The `SubscriptionCallback` signature is:
 using SubscriptionCallback = std::function<void(std::future<response::Value>)>;
 ```
 
+## `ResolverContext::NotifySubscribe` and `ResolverContext::NotifyUnsubscribe`
+
+If you use the async version of `subscribe` and `unsubscribe` which take a
+`std::launch` parameter, and you provide a default instance of the
+`Subscription` object to the `Request`/`Operations` constructor, you will get
+additional callbacks with the `ResolverContext::NotifySubscribe` and
+`ResolverContext::NotifyUnsubscribe` values for the
+`FieldParams::resolverContext` member. These are passed as part of the
+`subscribe` and `unsubscribe` calls on the default subscription object, and
+they provide an opportunity to acquire or release resources that are required
+to implement the subscription. You can provide separate implementations of the
+`Subscription` object as the default in the `Operations` constructor and as the
+payload of a specific `deliver` call, which will be resolved with
+`ResolverContext::Subscription`. If you do not provide a separate
+`Subscription` object in the `deliver` call, it will fall back to delivering a
+new event resolved against the default 
+
 ## Delivering Subscription Updates
 
 There are currently three `Request::deliver` overrides you can choose from when
@@ -46,33 +68,67 @@ parameter (which should match the `Subscription` type in the `schema`). It will
 unconditionally invoke every subscribed `SubscriptionCallback` callback with
 the response to its query:
 ```cpp
-void deliver(const SubscriptionName& name, const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(
+	const SubscriptionName& name, const std::shared_ptr<Object>& subscriptionObject) const;
 ```
 
 The second override adds argument filtering. It will look at the field 
 arguments in the subscription `query`, and if all of the required parameters
-in the `arguments` parameter are present and are an exact match it will dispatch the callback to that subscription:
+in the `arguments` parameter are present and are an exact match it will
+dispatch the callback to that subscription:
+```cpp
+GRAPHQLSERVICE_EXPORT void deliver(const SubscriptionName& name,
+	const SubscriptionArguments& arguments,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+```
+
+The third override adds directive filtering. It will look at both the field
+arguments and the directives with their own arguments in the subscription
+`query`, and if all of them match it will dispatch the callback to that
+subscription:
 ```cpp
-void deliver(const SubscriptionName& name, const SubscriptionArguments& arguments, const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(const SubscriptionName& name,
+	const SubscriptionArguments& arguments, const SubscriptionArguments& directives,
+	const std::shared_ptr<Object>& subscriptionObject) const;
 ```
 
-The last override lets you customize the the way that the required arguments
-are matched. Instead of an exact match or making all of the arguments required,
-it will dispatch the callback if the `apply` function parameter returns true
-for every required field in the subscription `query`.
+The last two overrides let you customize the the way that the required
+arguments and directives are matched. Instead of an exact match or making all
+of the arguments required, it will dispatch the callback if the `apply`
+function parameters return true for every required field and directive in the
+subscription `query`.
 ```cpp
-void deliver(const SubscriptionName& name, const SubscriptionFilterCallback& apply, const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(const SubscriptionName& name,
+	const SubscriptionFilterCallback& applyArguments,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(const SubscriptionName& name,
+	const SubscriptionFilterCallback& applyArguments,
+	const SubscriptionFilterCallback& applyDirectives,
+	const std::shared_ptr<Object>& subscriptionObject) const;
 ```
 
-By default, `deliver` invokes all of the `SubscriptionCallback` listeners with `std::future`
-payloads which are resolved on-demand but synchronously, using `std::launch::deferred` with the
-`std::async` function. There's also a version of each overload which  lets you substitute the
-`std::launch::async` option to begin executing the queries and invoke the callbacks on multiple
-threads in parallel:
+By default, `deliver` invokes all of the `SubscriptionCallback` listeners with
+`std::future` payloads which are resolved on-demand but synchronously, using
+`std::launch::deferred` with the `std::async` function. There's also a version
+of each overload which  lets you substitute the `std::launch::async` option to
+begin executing the queries and invoke the callbacks on multiple threads in
+parallel:
 ```cpp
-void deliver(std::launch launch, const SubscriptionName& name, const std::shared_ptr<Object>& subscriptionObject) const;
-void deliver(std::launch launch, const SubscriptionName& name, const SubscriptionArguments& arguments, const std::shared_ptr<Object>& subscriptionObject) const;
-void deliver(std::launch launch, const SubscriptionName& name, const SubscriptionFilterCallback& apply, const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(std::launch launch, const SubscriptionName& name,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(std::launch launch, const SubscriptionName& name,
+	const SubscriptionArguments& arguments,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(std::launch launch, const SubscriptionName& name,
+	const SubscriptionArguments& arguments, const SubscriptionArguments& directives,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(std::launch launch, const SubscriptionName& name,
+	const SubscriptionFilterCallback& applyArguments,
+	const std::shared_ptr<Object>& subscriptionObject) const;
+GRAPHQLSERVICE_EXPORT void deliver(std::launch launch, const SubscriptionName& name,
+	const SubscriptionFilterCallback& applyArguments,
+	const SubscriptionFilterCallback& applyDirectives,
+	const std::shared_ptr<Object>& subscriptionObject) const;
 ```
 
 ## Handling Multiple Operation Types
@@ -83,8 +139,9 @@ tell which operation type it is without parsing the query and searching for
 a specific operation name, so it's hard to tell whether you should call
 `resolve` or `subscribe` when the request is received that way. To help with
 that, there's a public `Request::findOperationDefinition` method which returns
-the operation type as a `std::string_view` along with a pointer to the AST node for
-the selected operation in the parsed query:
+the operation type as a `std::string_view` along with a pointer to the AST node
+for the selected operation in the parsed query:
 ```cpp
-std::pair<std::string_view, const peg::ast_node*> findOperationDefinition(peg::ast& root, std::string_view operationName) const;
+GRAPHQLSERVICE_EXPORT std::pair<std::string_view, const peg::ast_node*> findOperationDefinition(
+	peg::ast& query, std::string_view operationName) const;
 ```