Usability issues

[Geal]

here's a list of small usability issues around errors, messages we can improve, etc

[Geal]

using an invalid supergraph file:

$ ./target/debug/router -s ./Cargo.toml 
Nov 09 09:36:21.319 ERROR apollo_router: Failed to read schema: Could not read schema: Parsing error(s).
Nov 09 09:36:21.319  INFO router: Starting Apollo Router
*******************************************************************
⚠️  Experimental software, not YET recommended for production use ⚠️
*******************************************************************
Nov 09 09:36:21.319  INFO router: Stopped with error
Nov 09 09:36:21.319 ERROR router: Schema was not supplied.
Error: Schema was not supplied.

[o0Ignition0o]

#97 (review) is currently being worked on, i think it helps with missing, supergraphs.

Maybe we could expand on that and / or hint people to use rover to make sure the supergraph is valid

[Geal]

that would be nice. I'd like if the messages could be reordered a bit here:

Nov 09 09:36:21.319  INFO router: Starting Apollo Router
*******************************************************************
⚠️  Experimental software, not YET recommended for production use ⚠️
*******************************************************************
Nov 09 09:36:21.319 ERROR apollo_router: Failed to read schema: Could not read schema: Parsing error(s).
Nov 09 09:36:21.319 ERROR router: Schema was not supplied.
Nov 09 09:36:21.319  INFO router: Stopped with error

[Geal]

Returning structured errors

If I do this query:

query ExampleQuery {
  me {
    i
  }
}

I get the response:

{
  "hasNext": false,
  "errors": [
    {
      "message": "Query could not be planned: Query planning had errors: Planning errors: UNKNOWN: Cannot query field \"i\" on type \"User\".",
      "locations": [],
      "path": null,
      "extensions": {
        "type": "ValidationPlanningError",
        "reason": "Query planning had errors: Planning errors: UNKNOWN: Cannot query field \"i\" on type \"User\"."
      }
    }
  ],
  "data": null
}

The message is not great here, especially the big UNKNOWN

[Geal]

Subgraph connection error

If the subgraph is down and I do this query:

query ExampleQuery {
  me {
    id
  }
}

I get the following response:

{
  "errors": [
    {
      "message": "HTTP fetch failed from 'accounts': Request error: error sending request for url (http://localhost:4001/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)",
      "locations": [],
      "path": null,
      "extensions": {
        "type": "SubrequestHttpError",
        "service": "accounts",
        "reason": "Request error: error sending request for url (http://localhost:4001/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)"
      }
    }
  ],
  "data": null
}

I think we should display a more user friendly message. I also think we should hide the backend server's address.

In the logs, I see:

Nov 09 10:21:57.559 ERROR graphql_request:federated:execution:fetch:subfetch{service="accounts"}: apollo_router::http_subgraph: fetch_error="Reqwest(reqwest::Error { kind: Request, url: Url { scheme: \"http\", cannot_be_a_base: false, username: \"\", password: None, host: Some(Domain(\"localhost\")), port: Some(4001), path: \"/graphql\", query: None, fragment: None }, source: hyper::Error(Connect, ConnectError(\"tcp connect error\", Os { code: 111, kind: ConnectionRefused, message: \"Connection refused\" })) })

That log is not very actionable, we can display something like error sending to subgraph "accounts" at http://localhost:4001/ : Connection refused

[Geal]

If I have a subquery to the reviews subgraph (all subgraphs still down), there's an additional error message that is not too helpful either:

query ExampleQuery {
  me {
    id

    reviews {
      body
    }
  }
}

{
  "errors": [
    {
      "message": "HTTP fetch failed from 'accounts': Request error: error sending request for url (http://localhost:4001/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)",
      "locations": [],
      "path": null,
      "extensions": {
        "type": "SubrequestHttpError",
        "service": "accounts",
        "reason": "Request error: error sending request for url (http://localhost:4001/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)"
      }
    },
    {
      "message": "Could not find path: Could not find path in JSON.",
      "locations": [],
      "path": [
        "me"
      ],
      "extensions": {
        "type": "ExecutionPathNotFound",
        "reason": "Could not find path in JSON."
      }
    }
  ],
  "data": null
}

Logs:

Nov 09 10:32:01.136 ERROR graphql_request:federated:execution:sequence:fetch:subfetch{service="accounts"}: apollo_router::http_subgraph: fetch_error="Reqwest(reqwest::Error { kind: Request, url: Url { scheme: \"http\", cannot_be_a_base: false, username: \"\", password: None, host: Some(Domain(\"localhost\")), port: Some(4001), path: \"/graphql\", query: None, fragment: None }, source: hyper::Error(Connect, ConnectError(\"tcp connect error\", Os { code: 111, kind: ConnectionRefused, message: \"Connection refused\" })) })"
Nov 09 10:32:01.137 ERROR graphql_request:federated:execution:sequence: apollo_router_core::federated: Fetch error: Could not find path: Could not find path in JSON.

[Geal]

if the accounts subgraph is up but reviews is down:

query ExampleQuery {
  me {
    id

    reviews {
      body
    }
  }
}

response:

{
  "data": {
    "me": {
      "id": "1"
    }
  },
  "errors": [
    {
      "message": "HTTP fetch failed from 'reviews': Request error: error sending request for url (http://localhost:4002/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)",
      "locations": [],
      "path": null,
      "extensions": {
        "type": "SubrequestHttpError",
        "service": "reviews",
        "reason": "Request error: error sending request for url (http://localhost:4002/graphql): error trying to connect: tcp connect error: Connection refused (os error 111)"
      }
    },
    {
      "message": "Invalid content: Missing key `_entities`!",
      "locations": [],
      "path": [
        "me"
      ],
      "extensions": {
        "type": "ExecutionInvalidContent",
        "reason": "Missing key `_entities`!"
      }
    }
  ]
}

logs:

Nov 09 10:37:31.574 ERROR graphql_request:federated:execution:sequence:fetch:subfetch{service="reviews"}: apollo_router::http_subgraph: fetch_error="Reqwest(reqwest::Error { kind: Request, url: Url { scheme: \"http\", cannot_be_a_base: false, username: \"\", password: None, host: Some(Domain(\"localhost\")), port: Some(4002), path: \"/graphql\", query: None, fragment: None }, source: hyper::Error(Connect, ConnectError(\"tcp connect error\", Os { code: 111, kind: ConnectionRefused, message: \"Connection refused\" })) })"
Nov 09 10:37:31.574 ERROR graphql_request:federated:execution:sequence: apollo_router_core::federated: Fetch error: Invalid content: Missing key `_entities`!

[Geal]

Stacktrace appearing in graphql response

query ExampleQuery($skip: Boolean) {
  me {
    id

    reviews {
      id
      author @skip(if: $skip) {
        id
        reviews {
          id
        }
      }
    }
  }
}

response:

{
  "data": {
    "me": {
      "id": "1"
    }
  },
  "errors": [
    {
      "message": "Variable \"$skip\" of type \"Boolean\" used in position expecting type \"Boolean!\".",
      "locations": [
        {
          "line": 1,
          "column": 32
        },
        {
          "line": 1,
          "column": 128
        }
      ],
      "path": null,
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED",
        "exception": {
          "stacktrace": [
            "GraphQLError: Variable \"$skip\" of type \"Boolean\" used in position expecting type \"Boolean!\".",
            "    at Object.leave (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/graphql/validation/rules/VariablesInAllowedPositionRule.js:55:35)",
            "    at Object.leave (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/graphql/language/visitor.js:344:29)",
            "    at Object.leave (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/graphql/utilities/TypeInfo.js:390:21)",
            "    at visit (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/graphql/language/visitor.js:243:26)",
            "    at Object.validate (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/graphql/validation/validate.js:69:24)",
            "    at validate (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/apollo-server-core/dist/requestPipeline.js:221:34)",
            "    at Object.<anonymous> (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/apollo-server-core/dist/requestPipeline.js:118:42)",
            "    at Generator.next (<anonymous>)",
            "    at fulfilled (/home/geal/dev/router/dockerfiles/federation-demo/federation-demo/services/reviews/node_modules/apollo-server-core/dist/requestPipeline.js:5:58)",
            "    at processTicksAndRejections (internal/process/task_queues.js:97:5)"
          ]
        }
      }
    },
    {
      "message": "Invalid content: Missing key `_entities`!",
      "locations": [],
      "path": [
        "me"
      ],
      "extensions": {
        "type": "ExecutionInvalidContent",
        "reason": "Missing key `_entities`!"
      }
    }
  ]
}

logs:

Nov 09 10:46:49.466 ERROR graphql_request:federated:execution:sequence: apollo_router_core::federated: Fetch error: Invalid content: Missing key `_entities`!