Merge pull request #106 from d-exclaimation/v1/docs/fundamentals-inte…

…grations

v1: Standalone

Documentation/README.md

@@ -5,7 +5,7 @@ title: Introduction
 
 # Introduction to Pioneer
 
-!!!success 📣 Pioneer v1 is in beta!
+!!!success 📣 Pioneer v1 is generally available!
 <small>See what's new!</small>
 <br/>
 <small>Docs for Pioneer v0 are [available here](/v0/features/async-await)</small>

Documentation/fundamentals/faq.md

@@ -0,0 +1,8 @@
+---
+icon: cross-reference
+order: -1
+redirect: https://github.com/d-exclaimation/pioneer/discussions/categories/q-a
+---
+
+# FAQ
+

Documentation/getting-started.md

@@ -41,7 +41,7 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/GraphQLSwift/Graphiti.git", from: "1.2.1"),
         .package(url: "https://github.com/vapor/vapor.git", from: "4.67.1"),
-        .package(url: "https://github.com/d-exclaimation/pioneer", from: "1.0.0-beta")
+        .package(url: "https://github.com/d-exclaimation/pioneer", from: "1.0.0")
     ],
     targets: [
         .target(
@@ -271,31 +271,54 @@ For further reading, the team at [Apollo GraphQL](https://www.apollographql.com/
 
 Now, it's time to integrate Pioneer into the existing Vapor application using the resolver and schema declared before.
 
+### Pioneer configuration
+
+First, create an instance of Pioneer with the desired configuration.
+
+```swift #
+import Pioneer
+
+let server = try Pioneer(
+    schema: schema(),
+    resolver: Resolver(),
+    httpStrategy: .csrfPrevention,
+    introspection: true,
+    playground: .sandbox
+)
+```
+
+
 ### Basic Vapor application
 
-First, let's setup a basic Vapor application.
+Next, let's setup a basic Vapor application.
 
-```swift # main.swift
+```swift #2,4,14-16,18 main.swift
+import Pioneer
 import Vapor
 
 let app = try Application(.detect())
 
+let server = try Pioneer(
+    schema: schema(),
+    resolver: Resolver(),
+    httpStrategy: .csrfPrevention,
+    introspection: true,
+    playground: .sandbox
+)
+
 defer {
     app.shutdown()
 }
 
 try app.run()
 ```
 
-### Pioneer configuration
-
-Now, create an instance of Pioneer with the desired configuration.
+!!!success
+Pioneer can also run as a [standalone server](/web-frameworks/standalone) without needing to setup a Vapor application.
 
-```swift #1,6-12 main.swift
+==- Using standalone
+```swift #11-16 main.swift
 import Pioneer
-import Vapor
-
-let app = try Application(.detect())
 
 let server = try Pioneer(
     schema: schema(),
@@ -305,12 +328,16 @@ let server = try Pioneer(
     playground: .sandbox
 )
 
-defer {
-    app.shutdown()
-}
+try server.standaloneServer(
+    at: "graphql",
+    context: { req, res in
+        Context(req, res)
+    }
+)
 
-try app.run()
 ```
+===
+!!!
 
 ### Pioneer as Vapor middleware
 

Documentation/v1/changelog.md

@@ -1,6 +1,6 @@
 ---
 icon: history
-redirect: https://github.com/d-exclaimation/pioneer/releases/tag/1.0.0-beta
+redirect: https://github.com/d-exclaimation/pioneer/releases/tag/1.0.0
 order: 9
 ---
 

Documentation/v1/migrating.md

@@ -12,7 +12,7 @@ One of the big goal of [v1](/) is to bring fully bring a stable release of Pione
 Pioneer also now no longer a [Vapor](https://github.com/vapor/vapor)-only library and exposes more of its internal functions, structs, protocols, and classes which will allow integrations with other web frameworks.
 
 !!!success
-Pioneer [v1](/) will still have first-party integration for [Vapor](https://github.com/vapor/vapor).
+Pioneer [v1](/) will still have first-party integration for [Vapor](/web-frameworks/vapor).
 !!!
 
 ### Middleware
@@ -98,22 +98,22 @@ Pioneer now properly implement a WebSocket initialisation guard, which will fire
 
 ```swift #14-16
 let server = Pioneer(
-	schema: schema,
-	resolver: resolver
+    schema: schema,
+    resolver: resolver
 )
 
 app.middleware.use(
-	server.vaporMiddleware(
-		context: { req, res in
-			...
+    server.vaporMiddleware( 
+        context: { req, res in
+            ...
 		},
-		websocketContext: { req, payload, gql in
-			...
-		},
-		websocketGuard: { req, payload in 
-			...
-		}
-	)
+        websocketContext: { req, payload, gql in
+            ...
+        },
+        websocketGuard: { req, payload in
+            ...
+        }
+    )
 )
 ```
 
@@ -123,6 +123,35 @@ Pioneer [**v0**](/v0/guides/getting-started/server) uses 3 different paths for G
 
 In [**v1**](/), Pioneer will use the same path for all of those, and will instead determine from the request whether is a GraphQL over HTTP request, a GraphQL over WebSocket upgrade request, or a GraphQL IDE request.
 
+
+### Standalone server
+
+Pioneer will also now include option to run [standalone](/web-frameworks/standalone).
+
+```swift #6-16
+let server = Pioneer(
+    schema: schema,
+    resolver: resolver
+)
+
+try server.standaloneServer(
+    context: { req, res in
+        ...
+	},
+    websocketContext: { req, payload, gql in
+        ...
+    },
+    websocketGuard: { req, payload in
+        ...
+    }
+)
+```
+
+
+!!!success
+Under the hood, the standalone server uses the [Vapor](/web-frameworks/vapor) integration.
+!!!
+
 ## Other changes
 
 ### New defaults

Documentation/web-frameworks/integration.md

@@ -47,7 +47,7 @@ The important part is parsing into [GraphQLRequest](https://swiftpackageindex.co
     - The variables should be under `variables` as JSON string
         - This is probably percent encoded, and also need to be parse into `[String: Map]?` if available
     - As long the query string is accessible, the request is not malformed and we can construct a [GraphQLRequest](https://swiftpackageindex.com/d-exclaimation/pioneer/documentation/pioneer/graphqlrequest) using that.
-3. If [GraphQLRequest](https://swiftpackageindex.com/d-exclaimation/pioneer/documentation/pioneer/graphqlrequest) can't be retreive by both approach 1 and 2, the request is malformed and the response should have status code of 404 Bad Request.
+3. If [GraphQLRequest](https://swiftpackageindex.com/d-exclaimation/pioneer/documentation/pioneer/graphqlrequest) can't be retreive by both approach 1 and 2, the request is malformed and the response could also have status code of 400 Bad Request.
 
 ==- Example
 

Documentation/web-frameworks/standalone.md

@@ -0,0 +1,90 @@
+---
+icon: cpu
+order: 9
+---
+
+# Standalone
+
+Pioneer also come with **first-party** integration for a standalone server. This aims to make developing with Pioneer even faster by not having to worry about setting up the server.
+
+!!!success
+Under the hood, the standalone server uses the [Vapor](/web-frameworks/vapor) integration.
+!!!
+
+```swift #11
+import Pioneer
+
+let server = Pioneer(
+    schema: schema,
+    resolver: Resolver(),
+    websocketProtocol: .graphqlWs,
+    introspection: true,
+    playground: .sandbox
+)
+
+try server.standaloneServer()
+```
+
+## Configuration
+
+The standalone server allow some configuration to be better suited for your use case and environment.
+
+### Port, Host, and Env
+
+The [.standaloneServer](https://swiftpackageindex.com/d-exclaimation/pioneer/documentation/pioneer/pioneer) function can take specified:
+=== Port number (`port`)
+- Must be a valid port number and an `Integer`
+- Defaults to `4000`
+
+```swift #2
+try server.standaloneServer(
+    port: 8080
+)
+```
+===
+=== Hostname (`host`)
+- Must be a `String` containing either an IP address or `"localhost"`
+- Defaults to `127.0.0.1`
+
+```swift #2
+try server.standaloneServer(
+    host: "0.0.0.0"
+)
+```
+===
+=== Environment mode (`env`)
+- Must be either `"development"`, `"testing"`, `"production"`, `"dev"`, `"prod"`, or `"test"`.
+
+```swift #2
+try server.standaloneServer(
+    env: "production"
+)
+```
+
+<small><a href="https://docs.vapor.codes/basics/environment/#changing-environment">More info on environment mode</a></small>
+===
+
+### CORS
+
+Given that the standalone option is responsible setup the server, any middleware need to be configured by the function. 
+
+To allow CORS using a middleware, [.standaloneServer](https://swiftpackageindex.com/d-exclaimation/pioneer/documentation/pioneer/pioneer) function can take specified [CORSMiddleware.Configuration](https://docs.vapor.codes/advanced/middleware/?h=cors#cors-middleware).
+
+```swift #5-9
+try server.standaloneServer(
+    port: 443,
+    host: "0.0.0.0",
+    env: "production",
+    cors: .init(
+        allowedOrigin: .all,
+        allowedMethods: [.GET, .POST, .OPTIONS],
+        allowedHeaders: [.accept, .authorization, .contentType, .origin, .xRequestedWith, .userAgent, .accessControlAllowOrigin]
+    )  
+)
+```
+
+## Context
+
+Configuring context with the standalone server is identical with the [Vapor](/web-frameworks/vapor) integration.
+
+[!ref Context](/web-frameworks/vapor#context)

Documentation/web-frameworks/vapor.md

@@ -9,6 +9,25 @@ Pioneer will have a built-in **first-party** integration with [Vapor](https://gi
 
 This integration added a couple additional benefits.
 
+```swift #15
+import Pioneer
+import Vapor
+
+let app = try Application(.detect())
+
+let server = Pioneer(
+    schema: schema,
+    resolver: Resolver(),
+    websocketProtocol: .graphqlWs,
+    introspection: true,
+    playground: .sandbox
+)
+
+app.middleware.use(
+    server.vaporMiddleware()
+)
+```
+
 ## Context
 
 ### HTTP-based Context
@@ -253,4 +272,4 @@ The [Vapor](https://github.com/vapor/vapor) integration include other benefits s
 
 - Includes all security measurements done by Pioneer automatically (i.e. [CSRF Prevention](/features/graphql-over-http#csrf-and-xs-search))
 - Automatically operation check for HTTP methods using the given [HTTPStrategy](/features/graphql-over-http/#http-strategy)
-- Extensions for `CORSMiddleware.Configuration` for allowing Cloud based [GraphQL IDE](/features/graphql-ide)s
+- Extensions for `CORSMiddleware.Configuration` for allowing Cloud based [GraphQL IDE](/features/graphql-ide)s

README.md

@@ -11,7 +11,7 @@ Pioneer is an open-source, [spec-compliant](https://github.com/d-exclaimation/gr
 ## Setup
 
 ```swift
-.package(url: "https://github.com/d-exclaimation/pioneer", from: "1.0.0-beta")
+.package(url: "https://github.com/d-exclaimation/pioneer", from: "1.0.0")
 ```
 
 ## Swift for GraphQL