Merge branch 'main' into jwt-claim-pagination

Author: ddebrunner

dbquery/pagination/operations.graphql

@@ -1,5 +1,5 @@
 # Page through customers from a database connection based pagination
-query Customers($first: Int!, $after: String = "") {    
+query Customers($first: Int!, $after: String = "") {
   customers(first: $first, after: $after) {
     edges {
       node {

dbquery/pagination/tests/Test.js

@@ -2,7 +2,7 @@ const fs = require("fs");
 const path = require("node:path");
 const {
   deployAndRun,
-  authTypes,
+  stepzen,
   getTestDescription,
 } = require("../../../tests/gqltest.js");
 
@@ -44,7 +44,6 @@ describe(testDescription, function () {
           }
         }
       },
-      authType: authTypes.adminKey,
     },
     {
       label: "next set of results",
@@ -76,8 +75,7 @@ describe(testDescription, function () {
           }
         }
       },
-      authType: authTypes.adminKey,
     },
   ];
-  return deployAndRun(__dirname, tests);
+  return deployAndRun(__dirname, tests, stepzen.admin);
 });

dbquery/pings/postgresql/README.md

@@ -0,0 +1,64 @@
+# Ping PostgreSQL
+
+Simple schema that when deployed provides an easy way to check that a
+PostgreSQL database can be connected to from a GraphQL endpoint.
+
+## Setup
+
+Either set an environment variable or an `.env` file containing the URI of the PostgreSQL instance.
+
+Replace `<<xxx>>` values with the correct connection information.
+
+If a port number is required then add it to the host as `:1234`.
+
+If the password contains special characters then must be URL escaped.
+
+### Environment variable
+```
+export STEPZEN_PG_DB_URI=postgresql://<<host>>/<<database>>?user=<<user>>&password=<<password>>
+```
+
+### `.env` contents
+
+```
+STEPZEN_PG_DB_URI=postgresql://<<host>>/<<database>>?user=<<user>>&password=<<password>>
+```
+
+## Deploy
+
+```
+stepzen deploy
+```
+
+## Test
+
+```
+stepzen request '{ping{status}}'
+```
+
+## Example
+
+```
+>stepzen deploy 
+Deploying dbping/postgresql to StepZen... done in 443ms 🚀
+  ✓ 🔐 https://danville.us-east-a.ibm.stepzen.net/dbping/postgresql/__graphql
+  ✓ 🔐 wss://danville.us-east-a.ibm.stepzen.net/stepzen-subscriptions/dbping/postgresql/__graphql (subscriptions)
+
+You can test your hosted API with curl:
+
+curl https://danville.us-east-a.ibm.stepzen.net/dbping/postgresql/__graphql \
+   --header "Authorization: Apikey $(stepzen whoami --apikey)" \
+   --header "Content-Type: application/json" \
+   --data-raw '{
+     "query": "query SampleQuery { __schema { description queryType { fields {name} } } }"
+   }'
+
+stepzen request '{ping{status}}'
+{
+  "data": {
+    "ping": {
+      "status": "ok"
+    }
+  }
+}
+```

dbquery/pings/postgresql/config.yaml

@@ -0,0 +1,4 @@
+configurationset:
+  - configuration:
+      name: pgdb
+      uri: STEPZEN_PG_DB_URI

dbquery/pings/postgresql/index.graphql

@@ -0,0 +1,15 @@
+type Query {
+  """
+  Pings the configured database by running a SQL statement
+  that does not access any user tables or schema.
+  """
+  ping: Ping
+    @dbquery(
+      type: "postgresql"
+      query: "SELECT 'ok' AS status"
+      configuration: "pgdb"
+    )
+}
+type Ping {
+  status: String
+}

dbquery/pings/postgresql/stepzen.config.json

@@ -0,0 +1,3 @@
+{
+  "endpoint": "dbping/postgresql"
+}

dbquery/pings/postgresql/tests/Test.js

@@ -0,0 +1,11 @@
+const {
+  deployAndRun,
+  getTestDescription,
+} = require("../../../../tests/gqltest.js");
+
+testDescription = getTestDescription("snippets", __dirname);
+
+describe(testDescription, function () {
+  const tests = [];
+  return deployAndRun(__dirname, tests);
+});

executable/persisted/README.md

@@ -0,0 +1,135 @@
+# Persisted Documents
+
+GraphQL _executable documents_ containing at least one operation definition
+and optional fragment defintions can be persisted with a schema.
+
+## Overview
+
+The optional `executables` argument of `@sdl` takes a list of input document files
+that are GraphQL _executable documents_.
+
+```
+  @sdl(
+    files: []
+    executables: [{ document: "operations.graphql", persist: true }]
+  )
+```
+
+When a schema is deployed the _executable documents_ must validate successfully
+against the schema.
+
+By itself this can be used to validate applications' use
+of a GraphQL endpoint remain valid when the schema changes.
+This requires that the application loads GraphQL requests from
+files containing executable documents that are declared in the schema.
+
+In addition any _executable document_ in the schema that is marked with `persist: true`
+is loaded as a _persisted document_.
+
+A client uses a _persisted document_ by specifying its document identifier
+(based upon a SHA256 hash) in a request instead of the content of the _executable document_.
+
+For example instead of this POST body for a request:
+
+```
+{
+  "query": "{__typname}"
+}
+```
+
+a request can use this:
+
+```
+{
+"documentId": "sha256:ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"
+}
+```
+
+if an _executable document_ was declared in the schema with the matching SHA256 hash.
+
+The request parameters `operationName` and `variables` can be used as required with `documentId`.
+
+## Benefits
+
+Use of persisted documents typically saves network bandwidth as for real application requests
+the hash is smaller than the body of the _executable document_.
+
+In addition query requests can use HTTP GET while maintaining a reasonable sized URL
+that improves caching of URL requests. For example the above request can be a coded as an HTTP GET:
+
+```
+https://london.us-east-a.ibm.stepzen.net/api/customer/graphql?documentId=sha256%3Aecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38
+```
+
+## Executable Documents
+
+A good practice is to ensure that a CI/CD process ensures that _executable documents_ declared as
+part of the schema using `@sdl(executables:)` are formatted consistently, using tooling such as `prettier`.
+
+For example the simple _executable document_ shown above `{__typename}` stored in a document file
+and formatted will have contents (including a newline at the end):
+
+```
+{
+  __typename
+}
+```
+
+and thus a document identifier of `sha256:8d8f7365e9e86fa8e3313fcaf2131b801eafe9549de22373089cf27511858b39`.
+
+Clients can obtain the SHA256 hash for a document identifer using any standard mechanism for calculating hashes,
+for example on Linux/Unix systems this command can be used:
+
+```
+shasum -a 256 operations.graphql
+```
+
+When _executable documents_ are persisted using `@sdl(executables:)` the schema calculates the document identifiers automatically.
+
+## Example
+
+This example uses a simple mocked schema with a `Customer` type and a single `Query` field `customer`.
+
+`operations.graphql` contains three GraphQL query operations `Customer`, `CustomerEmail` and `CustomerName`
+each with a different selection against `Query.customer`.
+
+A client can execute them using these request parameters, shown as JavaScript:
+
+```
+{
+  documentId: "sha256:9d50d8e35b5882139e836a126f5d6d5a28cf41c5efd80a6e67f920d284b5f6d0",
+  operationName: "Customer",
+  variables: {
+    id: 1789,
+  },
+}
+```
+
+```
+{
+  documentId: "sha256:9d50d8e35b5882139e836a126f5d6d5a28cf41c5efd80a6e67f920d284b5f6d0",
+  operationName: "CustomerEmail",
+  variables: {
+    id: 2845,
+  },
+}
+```
+
+```
+{
+  documentId: "sha256:9d50d8e35b5882139e836a126f5d6d5a28cf41c5efd80a6e67f920d284b5f6d0",
+  operationName: "CustomerName",
+  variables: {
+    id: 3651,
+  },
+}
+```
+
+For example use `curl` and HTTP `GET` as follows:
+
+```
+curl \
+   --header "Authorization: Apikey $(stepzen whoami --apikey)" \
+   --header "Content-Type: application/json" \
+ 'https://london.us-east-a.ibm.stepzen.net/api/miscellaneous/graphql?documentId=sha256:9d50d8e35b5882139e836a126f5d6d5a28cf41c5efd80a6e67f920d284b5f6d0&operationName=Customer&variables=%7B%22id%22%3A%201789%7D'
+```

executable/persisted/index.graphql

@@ -0,0 +1,27 @@
+schema
+  @sdl(
+    files: []
+    # executables defines a list of GraphQL executable documents that
+    # are validated against the schema when deployed.
+    # If an executable document is marked as persist: true
+    # then it becomes a persisted document with the document identifier
+    # being tha SHA 256 hash of the document file.
+    executables: [{ document: "operations.graphql", persist: true }]
+  ) {
+  query: Query
+}
+
+type Query {
+  customer(id: ID!): Customer
+}
+type Customer @mock {
+  id: ID!
+  name: String! @mockfn(name: "LastName")
+  email: String @mockfn(name: "Email")
+  phone: String @mockfn(name: "Phone")
+  address: Address
+}
+type Address {
+  city: String @mockfn(name: "City")
+  zip: String @mockfn(name: "Zip")
+}

executable/persisted/operations.graphql

@@ -0,0 +1,24 @@
+query Customer($id: ID!) {
+  customer(id: $id) {
+    id
+    name
+    email
+    phone
+    address {
+      city
+      zip
+    }
+  }
+}
+
+query CustomerName($id: ID!) {
+  customer(id: $id) {
+    name
+  }
+}
+
+query CustomerEmail($id: ID!) {
+  customer(id: $id) {
+    email
+  }
+}