From 0a016312756ca68a3ee95447749b5c38d0ed360b Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 18 Nov 2022 22:12:34 +1300 Subject: [PATCH 1/2] docs: Updated docs to have all relevant information --- Documentation/fundamentals/faq.md | 8 ++ Documentation/getting-started.md | 53 ++++++++--- Documentation/v1/migrating.md | 55 +++++++++--- Documentation/web-frameworks/integration.md | 2 +- Documentation/web-frameworks/standalone.md | 90 +++++++++++++++++++ Documentation/web-frameworks/vapor.md | 21 ++++- .../Pioneer/Vapor/Pioneer+Standalone.swift | 16 ++-- 7 files changed, 209 insertions(+), 36 deletions(-) create mode 100644 Documentation/fundamentals/faq.md create mode 100644 Documentation/web-frameworks/standalone.md diff --git a/Documentation/fundamentals/faq.md b/Documentation/fundamentals/faq.md new file mode 100644 index 0000000..d89c189 --- /dev/null +++ b/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 + diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md index cf89a57..79856c7 100644 --- a/Documentation/getting-started.md +++ b/Documentation/getting-started.md @@ -271,15 +271,41 @@ 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() } @@ -287,15 +313,12 @@ defer { 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 diff --git a/Documentation/v1/migrating.md b/Documentation/v1/migrating.md index 9f59a90..ab04d33 100644 --- a/Documentation/v1/migrating.md +++ b/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 diff --git a/Documentation/web-frameworks/integration.md b/Documentation/web-frameworks/integration.md index 86fe800..7c7388c 100644 --- a/Documentation/web-frameworks/integration.md +++ b/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 diff --git a/Documentation/web-frameworks/standalone.md b/Documentation/web-frameworks/standalone.md new file mode 100644 index 0000000..36bf7d5 --- /dev/null +++ b/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" +) +``` + +More info on environment mode +=== + +### 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) \ No newline at end of file diff --git a/Documentation/web-frameworks/vapor.md b/Documentation/web-frameworks/vapor.md index ab9ca8d..25389df 100644 --- a/Documentation/web-frameworks/vapor.md +++ b/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 \ No newline at end of file +- Extensions for `CORSMiddleware.Configuration` for allowing Cloud based [GraphQL IDE](/features/graphql-ide)s diff --git a/Sources/Pioneer/Vapor/Pioneer+Standalone.swift b/Sources/Pioneer/Vapor/Pioneer+Standalone.swift index a1cde8d..4a1d7b3 100644 --- a/Sources/Pioneer/Vapor/Pioneer+Standalone.swift +++ b/Sources/Pioneer/Vapor/Pioneer+Standalone.swift @@ -27,7 +27,7 @@ extension Pioneer { port: Int = 4000, host: String = "127.0.0.1", env: String = "development", - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws { let app = try Application( .specified(port: port, host: host, env: env) @@ -41,7 +41,7 @@ extension Pioneer { app.middleware.use(middleware) if let cors = cors { - app.middleware.use(cors, at: .beginning) + app.middleware.use(CORSMiddleware(configuration: cors), at: .beginning) } try app.run() @@ -67,7 +67,7 @@ extension Pioneer { context: @escaping VaporHTTPContext, websocketContext: @escaping VaporWebSocketContext, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws { try vaporServer( middleware: vaporMiddleware( @@ -102,7 +102,7 @@ extension Pioneer { body: HTTPBodyStreamStrategy = .collect, context: @escaping VaporHTTPContext, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws { try vaporServer( middleware: vaporMiddleware( @@ -134,7 +134,7 @@ extension Pioneer { at path: PathComponent = "graphql", body: HTTPBodyStreamStrategy = .collect, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws where Context == Void { try vaporServer( middleware: vaporMiddleware( @@ -169,7 +169,7 @@ extension Pioneer { context: @escaping VaporHTTPContext, websocketContext: @escaping VaporWebSocketContext, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws { try vaporServer( middleware: vaporMiddleware( @@ -204,7 +204,7 @@ extension Pioneer { body: HTTPBodyStreamStrategy = .collect, context: @escaping VaporHTTPContext, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws { try vaporServer( middleware: vaporMiddleware( @@ -236,7 +236,7 @@ extension Pioneer { at path: [PathComponent], body: HTTPBodyStreamStrategy = .collect, websocketGuard: @escaping VaporWebSocketGuard = { _, _ in }, - cors: CORSMiddleware? = nil + cors: CORSMiddleware.Configuration? = nil ) throws where Context == Void { try vaporServer( middleware: vaporMiddleware( From 4fceebf104c557f6a516cc7466cda2a4b7013e47 Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 18 Nov 2022 22:14:25 +1300 Subject: [PATCH 2/2] docs: Updated to version 1.0.0 --- Documentation/README.md | 2 +- Documentation/getting-started.md | 2 +- Documentation/v1/changelog.md | 2 +- README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/README.md b/Documentation/README.md index 850bdad..d611ff4 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -5,7 +5,7 @@ title: Introduction # Introduction to Pioneer -!!!success 📣 Pioneer v1 is in beta! +!!!success 📣 Pioneer v1 is generally available! See what's new!
Docs for Pioneer v0 are [available here](/v0/features/async-await) diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md index 79856c7..9e92563 100644 --- a/Documentation/getting-started.md +++ b/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( diff --git a/Documentation/v1/changelog.md b/Documentation/v1/changelog.md index 58aa3d7..801304c 100644 --- a/Documentation/v1/changelog.md +++ b/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 --- diff --git a/README.md b/README.md index bddc109..7f50c12 100644 --- a/README.md +++ b/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