diff --git a/blog/graphql-angular-clients-2024-07-20.md b/blog/graphql-angular-clients-2024-07-20.md
index 7b561dfa01..85c4406436 100644
--- a/blog/graphql-angular-clients-2024-07-20.md
+++ b/blog/graphql-angular-clients-2024-07-20.md
@@ -75,13 +75,6 @@ Create a `tailcall` directory in the project root and add a jsonplaceholder.grap
```graphql
# File: tailcall/jsonplaceholder.graphql
-
-schema
- @server(port: 8000, hostname: "0.0.0.0")
- @upstream(httpCache: 42) {
- query: Query
-}
-
type Query {
posts: [Post]
@http(url: "http://jsonplaceholder.typicode.com/posts")
diff --git a/blog/graphql-introspection-security-2024-7-12.md b/blog/graphql-introspection-security-2024-7-12.md
index 06d8021e79..1b68314acc 100644
--- a/blog/graphql-introspection-security-2024-7-12.md
+++ b/blog/graphql-introspection-security-2024-7-12.md
@@ -78,13 +78,10 @@ Disabling introspection in production is crucial because it significantly reduce
In many GraphQL implementations, disabling introspection is straightforward. For example, in [Tailcall](https://tailcall.run/docs/server-directive/#introspection), you can disable introspection by setting the `introspection` option to `false`:
-```graphql
-schema
+```yaml
+server:
# highlight-next-line
- @server(introspection: false) {
- query: Query
- mutation: Mutation
-}
+ introspection: false
```
This configuration ensures that introspection is disabled.
diff --git a/blog/graphql-vue-clients-2024-08-01.md b/blog/graphql-vue-clients-2024-08-01.md
index 5216bb2ef3..3bd31a4edd 100644
--- a/blog/graphql-vue-clients-2024-08-01.md
+++ b/blog/graphql-vue-clients-2024-08-01.md
@@ -56,13 +56,6 @@ Then, create a `jsonplaceholder.graphql` file in this directory:
```graphql
# File: tailcall/jsonplaceholder.graphql
-
-schema
- @server(port: 8000, hostname: "0.0.0.0")
- @upstream(httpCache: 42) {
- query: Query
-}
-
type Query {
posts: [Post]
@http(url: "http://jsonplaceholder.typicode.com/posts")
diff --git a/docs/N+1.md b/docs/N+1.md
index d9688e7f35..66af5c3ffa 100644
--- a/docs/N+1.md
+++ b/docs/N+1.md
@@ -6,6 +6,9 @@ sidebar_label: N+1 Identification
image: /images/docs/n+1-issue.png
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
Detect and Solve GraphQL N+1 problem
@@ -178,14 +181,19 @@ If you run the query, at first you will observe a lot of duplicate requests are
This happens because of the 100 posts, a lot them are authored by the same user and by default Tailcall will make a request for every user when requested. You can fix this by setting [dedupe](./directives/graphQL.md#dedupe) to `true` in [server](./config/server.md).
-```graphql {3}
-schema
- @server(
+
+
+
+```yaml
+server:
dedupe: true
- port: 8000) {
- query: Query
-}
+```
+
+
+
+
+```graphql
type Query {
# ...
}
@@ -199,6 +207,9 @@ type User {
}
```
+
+
+
When you enable `dedupe`, for each downstream request, Tailcall will automatically using a dataloader deduplicate all upstream requests and instead of making 100 it will only make 10 requests for unique users:
```text {6-16}
@@ -322,11 +333,7 @@ The described changes introduce two significant tweaks to the `@http` directive:
Let's see what the server logs when you now start Tailcall with the updated configuration:
-```graphql {21-22}
-schema @server(port: 8000) {
- query: Query
-}
-
+```graphql
type Query {
posts: [Post]
@http(url: "http://jsonplaceholder.typicode.com/posts")
@@ -341,7 +348,9 @@ type Post {
@http(
url: "http://jsonplaceholder.typicode.com/users"
query: [{key: "id", value: "{{.value.userId}}"}]
+ #highlight-start
batchKey: ["id"]
+ #highlight-end
)
}
diff --git a/docs/apollo-studio.md b/docs/apollo-studio.md
index 421f158a80..af24435393 100644
--- a/docs/apollo-studio.md
+++ b/docs/apollo-studio.md
@@ -5,6 +5,9 @@ slug: integrate-apollo-studio-graphql-tailcall
sidebar_label: Apollo Studio
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
This guide illustrates how to configure `tailcall` to send usage metrics to [Apollo Studio](https://studio.apollographql.com).
## Creating a monolith graph
@@ -42,20 +45,28 @@ To see the metrics for you queries follow these instructions:
1. Start `tailcall` with the appropriate configuration for Apollo (click [here](/docs/cli.md#start) to know more). Below is an example of what a config may look like:
- ```graphql
- schema
- @server(port: 8000)
- @telemetry(
- export: {
- apollo: {
- apiKey: ""
- graphRef: ""
- }
- }
- ) {
- query: Query
- }
+
+
+ ```yaml
+ server:
+ port: 8000
+
+ telemetry:
+ export:
+ apollo:
+ apiKey: ""
+ graphRef: ""
+
+ links:
+ - src: main.graphql
+ ```
+
+
+
+
+
+ ```graphql
type Query {
posts: [Post]
@http(
@@ -71,6 +82,9 @@ To see the metrics for you queries follow these instructions:
}
```
+
+
+
1. Visit `http://localhost:8000/graphql` and create a query with an appropriate name (below is an example query named `MyQuery`) and run it multiple times to send the metrics to Apollo Studio.
:::tip
diff --git a/docs/auth.md b/docs/auth.md
index 0179f2605f..0bbe72e4e7 100644
--- a/docs/auth.md
+++ b/docs/auth.md
@@ -5,6 +5,9 @@ slug: field-level-access-control-graphql-authentication
sidebar_label: Authentication
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
This guide will walk you through entity level authentication in GraphQL and how it could be achieved with Tailcall.
## What is Authentication?
@@ -46,23 +49,34 @@ to know more about how to use it, read the following articles:
Enabling support for authentication in Tailcall could be done in two steps:
-1. With the help of [`@link` directive](./config/links.md) connect multiple authentication files as you need for different provides. To connect it use either [`Htpasswd`](./config/links.md#htpasswd) or [`Jwks`](./config/links.md#jwks) link type
+1. With the help of [`links` config](./config/links.md) connect multiple authentication files as you need for different provides. To connect it use either [`Htpasswd`](./config/links.md#htpasswd) or [`Jwks`](./config/links.md#jwks) link type
2. Mark that some type of field requires authentication to be fetched with the help of [`@protected` directive](./directives/protected.md)
Your config could look like this now:
-```graphql
-schema
- @server(port: 8000)
+
+
+
+```yaml
+server:
+ port: 8000
+links:
+ - src: main.graphql
#highlight-start
- @link(id: "auth-basic", type: Htpasswd, src: "htpasswd")
- @link(id: "auth-jwt", type: Jwks, src: "jwks.json") {
+ - id: auth-basic
+ type: Htpasswd
+ src: htpasswd
+ - id: auth-jwt
+ type: Jwks
+ src: jwks.json
#highlight-end
+```
- query: Query
- mutation: Mutation
-}
+
+
+
+```graphql
type Query {
posts: [Post]
@http(url: "http://jsonplaceholder.typicode.com/posts")
@@ -104,6 +118,9 @@ type Post {
}
```
+
+
+
In that case the whole `User` type and `Post.body` are marked as protected and therefore requiring authentication to resolve its content. That means following points:
- any query for `Post.body` will require authentication
@@ -270,7 +287,7 @@ Since this file stores secure information make sure to hash the password you use
### Basic Auth GraphQL Configuration
-To use Basic Auth you should first include htpasswd file generated from [Prerequisites](#prerequisites) with the help of [`@link` directive](./config/links.md#htpasswd).
+To use Basic Auth you should first include htpasswd file generated from [Prerequisites](#prerequisites) with the help of [`links` config](./config/links.md#htpasswd).
We can use that file as an example for it that has data for `testuser:mypassword` credentials in encrypted format:
@@ -278,17 +295,28 @@ We can use that file as an example for it that has data for `testuser:mypassword
testuser:$2y$10$wJ/mZDURcAOBIrswCAKFsO0Nk7BpHmWl/XuhF7lNm3gBAFH3ofsuu
```
-After adding `@link` you can use the [`@protected` directive](./directives/protected.md) to mark the fields that requiring success authentication to be requested.
+After adding `links` you can use the [`@protected` directive](./directives/protected.md) to mark the fields that requiring success authentication to be requested.
The whole example could look like this:
-```graphql
-schema
- @server(port: 8000)
- @link(id: "auth-basic", type: Htpasswd, src: "htpasswd") {
- query: Query
-}
+
+
+
+```yaml
+server:
+ port: 8000
+links:
+ - src: main.graphql
+ - id: auth-basic
+ type: Htpasswd
+ src: htpasswd
+```
+
+
+
+
+```graphql
type Query {
user(id: Int!): User
@http(
@@ -306,6 +334,9 @@ type User @protected {
}
```
+
+
+
### Making test request
Now you can run the example file with Tailcall and try to make a query for data with specifying credentials.
@@ -353,7 +384,7 @@ To create this file you can use available web-tools like [JWK creator](https://r
### JWT Auth GraphQL Configuration
-To use JWT you should first include JWKS file generated from [Prerequisites](#prerequisites) with the help of [`@link` directive](./config/links.md#jwks).
+To use JWT you should first include JWKS file generated from [Prerequisites](#prerequisites) with the help of [`links` config](./config/links.md#jwks).
We can use that file as an example for it:
@@ -372,17 +403,28 @@ We can use that file as an example for it:
}
```
-After adding `@link` you can use the [`@protected` directive](./directives/protected.md) to mark the fields that requiring success authentication to be requested.
+After adding `links` you can use the [`@protected` directive](./directives/protected.md) to mark the fields that requiring success authentication to be requested.
The whole example could look like this:
-```graphql
-schema
- @server(port: 8000)
- @link(id: "auth-jwks", type: Jwks, src: "jwks.json") {
- query: Query
-}
+
+
+
+```yaml
+server:
+ port: 8000
+links:
+ - src: main.graphql
+ - id: auth-jwks
+ type: Jwks
+ src: jwks.json
+```
+
+
+
+
+```graphql
type Query {
user(id: Int!): User
@http(
@@ -400,6 +442,9 @@ type User @protected {
}
```
+
+
+
### Making test request
Now you can run the example file with Tailcall and try to make a query for data with specifying credentials.
diff --git a/docs/cli.md b/docs/cli.md
index 3e0b633277..187852835d 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -244,6 +244,31 @@ preset:
+---
+
+
+
+
+```yaml
+server:
+ port: 8000
+links:
+ - src: main.graphql
+```
+
+
+
+
+
+```graphql
+
+```
+
+
+
+
+---
+
### Inputs
The `inputs` section specifies the sources from which the GraphQL configuration should be generated. Each source can be either a REST endpoint or a protobuf file.
diff --git a/docs/client-tuning.md b/docs/client-tuning.md
index e4402814e0..05132aaf69 100644
--- a/docs/client-tuning.md
+++ b/docs/client-tuning.md
@@ -50,7 +50,7 @@ Connection pooling mitigates these issues by reusing existing connections for re
## Tuning HTTP Client
-Tailcall uses connection pooling by default and sets up with default tuning suitable for most use cases. You might need to further tune the HTTP client to improve your application's performance. Tailcall DSL provides a directive named [`@upstream`](./config/upstream.md) for this purpose.
+Tailcall uses connection pooling by default and sets up with default tuning suitable for most use cases. You might need to further tune the HTTP client to improve your application's performance. Tailcall DSL provides a configuration named [`upstream`](./config/upstream.md) for this purpose.
:::note
Connection pooling optimizes HTTP/1. Since HTTP/2 and HTTP/3 support multiplexing, pooling enabled does not noticeably affect performance.
@@ -62,15 +62,11 @@ When using HTTP/1.x, tune the connection pool with the following parameters:
`poolMaxIdlePerHost` specifies the allowed number of idle connections per host, defaulting to `60`. Example:
-```graphql showLineNumbers
-schema
- @upstream(
- # highlight-start
- poolMaxIdlePerHost: 60
- # highlight-end
- ) {
- query: Query
-}
+```yaml showLineNumbers
+upstream:
+ # highlight-start
+ poolMaxIdlePerHost: 60
+ # highlight-end
```
Too idle connections can unnecessarily consume memory and ports, while too few might cause delays as new connections need frequent establishment. `poolMaxIdlePerHost` ensures judicious use of network and memory resources, avoiding wastage on seldom-used connections.
@@ -84,15 +80,11 @@ For applications connecting to hosts, set this value lower to keep connections a
Tailcall provides a parameter named `tcpKeepAlive` for the upstream which defaults to 5 seconds. Example:
schema
-```graphql
-@upstream (
-# highlight-start
+```yaml
+upstream:
+ # highlight-start
tcpKeepAlive: 300
-# highlight-end
-) {
-query: Query
-}
-
+ # highlight-end
```
### connectTimeout
@@ -101,15 +93,11 @@ query: Query
Tailcall offers a `connectTimeout` parameter to set the connection timeout in seconds for the HTTP client, defaulting to 60 seconds. Example:
-```graphql showLineNumbers
-schema
- @upstream(
- # highlight-start
- connectTimeout: 10
- # highlight-end
- ) {
- query: Query
-}
+```yaml showLineNumbers
+upstream:
+ # highlight-start
+ connectTimeout: 10
+ # highlight-end
```
In summary, maximizing HTTP client performance requires understanding the underlying protocols and configuring client settings through testing. This ensures efficient, robust, and high-performing client-server communication, crucial for the smooth operation of modern web applications.
diff --git a/docs/config-generation.md b/docs/config-generation.md
index 4cb93125f3..3533e197bc 100644
--- a/docs/config-generation.md
+++ b/docs/config-generation.md
@@ -236,7 +236,7 @@ type Query {
path: "./jsonplaceholder.graphql"
format: "graphQL"
schema:
- query: "Query"
+ query: "Query"
```
@@ -296,7 +296,7 @@ tailcall gen ./config.json
Generated Configuration looks like following.
```graphql showLineNumbers title="Generated GraphQL Configuration"
-schema @server @upstream {
+schema {
mutation: Mutation
}
@@ -374,29 +374,29 @@ Tailcall simplifies the process of generating GraphQL schemas from gRPC. By spec
-
- ```yml showLineNumbers
- inputs:
- - proto:
- src: "./news.proto"
- url: "http://localhost:50051"
- - proto:
- src: "./news.proto"
- url: "http://localhost:8080/news.NewsService/"
- connectRPC: true
- protoPaths:
- - "./protos"
- preset:
- mergeType: 1.0
- output:
- path: "./jsonplaceholder.graphql"
- format: "graphQL"
- schema:
- query: "Query"
- ```
-
-
+ ```yml showLineNumbers
+ inputs:
+ - proto:
+ src: "./news.proto"
+ url: "http://localhost:50051"
+ - proto:
+ src: "./news.proto"
+ url: "http://localhost:8080/news.NewsService/"
+ connectRPC: true
+ protoPaths:
+ - "./protos"
+ preset:
+ mergeType: 1.0
+ output:
+ path: "./jsonplaceholder.graphql"
+ format: "graphQL"
+ schema:
+ query: "Query"
+ ```
+
+
+
Let's understand the above configuration file.
@@ -420,11 +420,21 @@ Let's understand the above configuration file.
**Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
-```graphql showLineNumbers title="Generated GraphQL Configuration"
-schema @link(src: "./news.proto", type: Protobuf) @server {
- query: Query
-}
+
+
+```yaml title="Generated GraphQL Configuration"
+links:
+ - src: main.graphql
+ - type: Protobuf
+ src: ./news.proto
+```
+
+
+
+
+
+```graphql showLineNumbers title="Generated GraphQL Configuration"
type News @tag(id: "news.News") {
id: Int
title: String
@@ -437,6 +447,9 @@ type Query {
}
```
+
+
+
for more insights on how gPRC works with GraphQL, you can read this [GraphQL over gRPC](grpc.md) article.
### Hybrid Integration (REST + gRPC)
@@ -540,12 +553,22 @@ tailcall gen ./config.json
**Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
-```graphql showLineNumbers
-schema @link(src: "./news.proto", type: Protobuf) @server {
- query: Query
-}
+
+
-type News @tag(id: "news.News") {
+```yaml title="Generated GraphQL Configuration"
+links:
+ - src: main.graphql
+ - type: Protobuf
+ src: ./news.proto
+```
+
+
+
+
+
+```graphql showLineNumbers title="Generated GraphQL Configuration"
+type News {
id: Int
title: String
content: String
@@ -566,6 +589,9 @@ type Query {
}
```
+
+
+
## Understanding Presets
This section is optional and can be used to generate a more optimized configuration by applying various transformers that improve the config generation process, such as automatically inferring meaningful names of the types, merging duplicate types, removing unused types, and more. If you find that the generated GraphQL configuration is sufficient for your needs, you can skip this section.
diff --git a/docs/context.md b/docs/context.md
index 16b30c4247..182f1e5a2c 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -5,6 +5,9 @@ slug: graphql-resolver-context-tailcall
sidebar_label: Resolver Context
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
Within Tailcall, `Context` is a pivotal component that allows for dynamic retrieval of values during the resolution of fields for a given type within the schema.
## Schema Definition
@@ -72,14 +75,23 @@ type Query {
`vars` offers a mechanism for defining reusable variables within the configuration. Unlike `env`, these are embedded and can be universally applied across configurations.
-```graphql showLineNumbers
-schema
- @server(
- vars: {key: "apiKey", value: "{{.env.AUTH_TOKEN}}"}
- ) {
- query: Query
-}
+
+
+
+```yaml
+server:
+ vars:
+ - key: apiKey
+ value: "{{.env.AUTH_TOKEN}}"}
+links:
+ - src: main.graphql
+```
+
+
+
+
+```graphql showLineNumbers
type Query {
user(id: ID!): [User]
@http(
@@ -94,6 +106,9 @@ type Query {
}
```
+
+
+
Here, the variable `apiKey` is set using an environment variable and subsequently utilized in the `Authorization` header for HTTP requests.
### headers
diff --git a/docs/contributors/integration-testing.md b/docs/contributors/integration-testing.md
index 2edb531ae9..72738bb01a 100644
--- a/docs/contributors/integration-testing.md
+++ b/docs/contributors/integration-testing.md
@@ -235,10 +235,10 @@ function onRequest({request}) {
}
```
-```graphql @config
-schema @link(file: "worker.js") {
- query: Query
-}
+```yaml @config
+links:
+ - type: Script
+ src: worker.js
```
````
diff --git a/docs/data-dog.md b/docs/data-dog.md
index d8d19d658c..bb6692d271 100644
--- a/docs/data-dog.md
+++ b/docs/data-dog.md
@@ -91,13 +91,11 @@ This guide is based on the [official doc](https://docs.datadoghq.com/getting_sta
5. **Update Tailcall Configuration:**
Add telemetry support to your Tailcall configuration as follows:
- ```graphql
- schema
- @telemetry(
- export: {otlp: {url: "http://localhost:4317"}}
- ) {
- query: Query
- }
+ ```yaml
+ telemetry:
+ export:
+ otlp:
+ url: "http://localhost:4317"
```
6. **Set the Environment Variable for Tailcall:**
diff --git a/docs/directives/call.md b/docs/directives/call.md
index 025a6904e3..16b7374437 100644
--- a/docs/directives/call.md
+++ b/docs/directives/call.md
@@ -175,10 +175,6 @@ The `@call` directive can be used to combine multiple resolvers in a sequence, p
Consider a scenario where we have three operations (`a`, `b`, `c`), each extracting a specific part of the input:
```graphql showLineNumbers
-schema @server {
- query: Query
-}
-
type Query {
a(input: JSON): JSON
@expr(body: {value: "{{.args.input.a}}"})
@@ -194,10 +190,6 @@ type Query {
We can create a new `abc` operation that calls `a`, `b`, and `c` in sequence to extract deeply nested data:
```graphql showLineNumbers
-schema @server {
- query: Query
-}
-
type Query {
a(input: JSON): JSON
@expr(body: {value: "{{.args.input.a}}"})
diff --git a/docs/directives/grpc.md b/docs/directives/grpc.md
index 3a5b4b8193..8a4fc566b4 100644
--- a/docs/directives/grpc.md
+++ b/docs/directives/grpc.md
@@ -4,6 +4,9 @@ description: The @grpc directive enables the resolution of GraphQL fields via gR
slug: ../grpc-directive
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
The `@grpc` directive allows GraphQL fields to be resolved by fetching data through gRPC services, facilitating powerful integrations between GraphQL and gRPC.
## `@grpc` Directive Definition
@@ -25,16 +28,29 @@ directive @grpc(
Here's an example demonstrating the use of the `@grpc` directive:
-```graphql showLineNumbers
-schema @link(src: "./users.proto", type: Protobuf) {
- query: Query
-}
+
+
+
+```yaml
+links:
+ - src: main.graphql
+ - type: Protobuf
+ src: ./users.proto
+```
+
+
+
+
+```graphql showLineNumbers
type Query {
users: [User] @grpc(method: "users.UserService.ListUsers")
}
```
+
+
+
In this example, the `users` field fetches data from the gRPC method `UserService.ListUsers`.
### Defining gRPC Services
@@ -72,12 +88,12 @@ message UserGetReply {
It is mandatory to have a package name in a protobuf file.
:::
-Linking this file within a GraphQL schema is facilitated by the `@link` directive, as shown below:
+Linking this file within a GraphQL schema is facilitated by the `links` config, as shown below:
-```graphql
-schema @link(src: "./users.proto", type: Protobuf) {
- query: Query
-}
+```yaml
+links:
+ - type: Protobuf
+ src: ./users.proto
```
Tailcall automatically resolves the protobuf file for any methods referenced in the `@grpc` directive.
diff --git a/docs/directives/js.md b/docs/directives/js.md
index d01f7791ed..67e30cb763 100644
--- a/docs/directives/js.md
+++ b/docs/directives/js.md
@@ -4,6 +4,9 @@ description: The @js directive allows you to use JavaScript functions to resolve
slug: ../js-directive
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
The `@js` directive is defined as follows:
```graphql title="Directive Definition" showLineNumbers
@@ -41,14 +44,25 @@ function resolve(val) {
Here is an example of how the `@js` directive is used within a GraphQL schema:
-```gql showLineNumbers
-schema
- @link(type: Script, src: "./scripts/foo.js")
- @server(port: 8000)
- @upstream(httpCache: true) {
- query: Query
-}
+
+
+
+```yaml
+server:
+ port: 8000
+upstream:
+ httpCache: true
+links:
+ - src: main.graphql
+ - type: Script
+ src: ./scripts/foo.js
+```
+
+
+
+
+```gql showLineNumbers
type Query {
posts: [Post]
@http(url: "https://jsonplaceholder.typicode.com/posts")
@@ -63,6 +77,9 @@ type Post {
}
```
+
+
+
## Error Handling
When using the `@js` directive, it is important to handle errors within your JavaScript functions. For example, you can use try-catch blocks to catch and handle any errors that occur during the resolution process.
diff --git a/docs/directives/protected.md b/docs/directives/protected.md
index 5dccf4bca1..dea3230724 100644
--- a/docs/directives/protected.md
+++ b/docs/directives/protected.md
@@ -4,6 +4,9 @@ description: The @protected directive ensures that a user must be authenticated
slug: ../protected-directive
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
The `@protected` directive ensures that a user must be authenticated to access certain data.
```graphql title="Directive Definition" showLineNumbers
@@ -23,14 +26,14 @@ The `@protected` directive designates a type or field as protected, meaning that
To use the `@protected` directive, you must configure at least one authentication provider using the [`links`](../config/links.md) configuration, such as `Htpasswd` or `Jwks`.
-```graphql title="Authentication Provider Configuration" showLineNumbers
-schema
- @server
- @upstream
- @link(id: "basic", type: Htpasswd, src: ".htpasswd_a")
- @link(id: "jwt", type: Jwks, src: "jwks.json") {
- query: Query
-}
+```yaml title="Authentication Provider Configuration" showLineNumbers
+links:
+ - id: basic
+ type: Htpasswd
+ src: ".htpasswd_a"
+ - id: jwt
+ type: Jwks
+ src: jwks.json
```
## How It Works
@@ -91,16 +94,28 @@ Consider the following schema and authentication configuration:
### Schema
-```graphql showLineNumbers
-schema
- @server
- @upstream
- @link(id: "a", src: ".htpasswd_a", type: Htpasswd)
- @link(id: "b", src: ".htpasswd_b", type: Htpasswd)
- @link(id: "c", src: ".htpasswd_c", type: Htpasswd) {
- query: Query
-}
+
+
+
+```yaml
+links:
+ - src: main.graphql
+ - id: a
+ type: Htpasswd
+ src: .htpasswd_a
+ - id: b
+ type: Htpasswd
+ src: .htpasswd_b
+ - id: c
+ type: Htpasswd
+ src: .htpasswd_c
+```
+
+
+
+
+```graphql showLineNumbers
type Query {
animals: [Animal!]!
@expr(
@@ -127,6 +142,9 @@ type Bird {
}
```
+
+
+
### Authentication Files
#### `.htpasswd_a`
diff --git a/docs/directives/rest.md b/docs/directives/rest.md
index e48efc73bf..36e021e9f4 100644
--- a/docs/directives/rest.md
+++ b/docs/directives/rest.md
@@ -4,6 +4,9 @@ description: The @rest directive maps fields to REST API endpoints, allowing Gra
slug: ../rest-directive
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
The `@rest` directive is defined as follows:
```graphql title="Directive Definition" showLineNumbers
@@ -37,14 +40,21 @@ API orchestration is essential, yet not all can adopt GraphQL despite its benefi
Define GraphQL types and queries, using the `@rest` directive to map fields to REST API endpoints.
-`schema.graphql`
+
+
-```graphql
-schema
- @link(type: Operation, src: "user-operation.graphql") {
- query: Query
-}
+```yaml
+links:
+ - src: main.graphql
+ - type: Operation
+ src: user-operation.graphql
+```
+
+
+
+
+```graphql
type Query {
user(id: Int!): User
@rest(method: "GET", path: "/users/{{.args.id}}")
@@ -57,7 +67,9 @@ type User {
}
```
-`user-operation.graphql`
+
+
+
```graphql
query ($id: Int!) @rest(method: GET, path: "/user/$id") {
@@ -68,6 +80,10 @@ query ($id: Int!) @rest(method: GET, path: "/user/$id") {
}
```
+
+
+
+
![REST Demo](/images/docs/rest-user.png)
This example demonstrates how to define a simple query to fetch user data from a REST endpoint using the `@rest` directive. By leveraging `@rest`, GraphQL can serve as a layer over RESTful services, combining REST's simplicity with GraphQL's flexibility.
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index 82d9da2c98..17b466febf 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -135,15 +135,19 @@ The command will ask you a few questions and based on your input bootstrap a new
For our first example, we are going to compose a GraphQL schema from the REST APIs at https://jsonplaceholder.typicode.com, a free online REST API with some fake data.
We will use the API at `/users` to get a list of users, and `/users/:id/posts` to get the posts for each user, and compose them into a single GraphQL schema.
-Create a new file and paste the contents into it.
+Create a new file `main.yaml` to specify runtime config with following content:
+
+```yaml showLineNumbers
+# Specify server configuration: Start GraphQL server at 0.0.0.0:8000
+server:
+ port: 8000
+links:
+ - src: ./main.graphql
+```
-```graphql showLineNumbers
-schema
- # Specify server configuration: Start GraphQL server at 0.0.0.0:8000
- @server(port: 8000) {
- query: Query
-}
+Then create schema file `main.graphql`:
+```graphql showLineNumbers
type Query {
# Specify the http path for the users query
users: [User] @http(url: "http://jsonplaceholder.typicode.com/users")
@@ -170,7 +174,7 @@ type Post {
}
```
-The above file is a standard `.graphQL` file, with some minor additions such as `@upstream` and `@http` directives. Basically we specify the GraphQL schema and how to resolve that GraphQL schema in the same file, without having to write any code!
+The above file is a standard `.graphQL` file, with some minor additions such as `@http` directives. Basically we specify the GraphQL schema and how to resolve that GraphQL schema in the same file, without having to write any code!
## Starting the GraphQL server
diff --git a/docs/grpc.md b/docs/grpc.md
index 085ab86f38..88c9051c00 100644
--- a/docs/grpc.md
+++ b/docs/grpc.md
@@ -6,6 +6,9 @@ slug: graphql-grpc-tailcall
image: /images/docs/graphql_on_grpc.png
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
How to build GraphQL over gRPC APIs
@@ -125,16 +128,20 @@ type Query {
Also, let's specify options for Tailcall's ingress and egress at the beginning of the config using [`server`](./config/server.md) and [`upstream`](./config/upstream.md) options.
-```graphql
-schema @server(port: 8000) @upstream(httpCache: 42) {
- query: Query
-}
+```yaml
+server:
+ port: 8000
+upstream:
+ httpCache: 42
```
-To specify the protobuf file to read types from, use the `@link` directive with the type `Protobuf` on the schema. `id` is an important part of the definition that will be used by the `@grpc` directive later
+To specify the protobuf file to read types from, use the `links` config with the type `Protobuf` on the schema. `id` is an important part of the definition that will be used by the `@grpc` directive later
-```graphql
-schema @link(id: "news", src: "./news.proto", type: Protobuf)
+```yaml
+links:
+ - id: news
+ type: Protobuf
+ src: ./news.proto
```
Now you can connect GraphQL types to gRPC types. To do this you may want to explore more about [`@grpc` directive](./directives/grpc.md). Its usage is pretty straightforward and requires you to specify the path to a method that should be used to make a call. The method name will start with the package name, followed by the service name and the method name, all separated by the `.` symbol.
@@ -159,16 +166,28 @@ type Query {
Wrapping up the whole result config that may look like this:
-```graphql
-# file: app.graphql
+
+
+
+```yaml
+server:
+ port: 8000
+upstream:
+ httpCache: 42
+ batch:
+ delay: 10
+links:
+ - src: main.graphql
+ - id: news
+ type: Protobuf
+ src: ./news.proto
+```
-schema
- @server(port: 8000)
- @upstream(httpCache: 42)
- @link(id: "news", src: "./news.proto", type: Protobuf) {
- query: Query
-}
+
+
+
+```graphql
type Query {
news: NewsData!
@grpc(
@@ -199,6 +218,9 @@ type NewsData {
}
```
+
+
+
Start the server by pointing it to the config.
```
@@ -237,14 +259,28 @@ Another important feature of the `@grpc` directive is that it allows you to impl
In our protobuf example file, we have a method called `GetMultipleNews` that we can use. To enable batching we need to enable [`upstream.batch` option](./config/upstream.md#batch) first and specify `batchKey` option for the `@grpc` directive.
-```graphql
-schema
- @server(port: 8000)
- @upstream(httpCache: 42, batch: {delay: 10})
- @link(id: "news", src: "./news.proto", type: Protobuf) {
- query: Query
-}
+
+
+
+```yaml
+server:
+ port: 8000
+upstream:
+ httpCache: 42
+ batch:
+ delay: 10
+links:
+ - src: main.graphql
+ - id: news
+ type: Protobuf
+ src: ./news.proto
+```
+
+
+
+
+```graphql
type Query {
newsById(news: NewsInput!): News!
@grpc(
@@ -257,6 +293,9 @@ type Query {
}
```
+
+
+
Restart the GraphQL server and make the query with multiple news separately, e.g.:
```graphql
@@ -282,14 +321,10 @@ gRPC reflection is a potent feature enabling clients to dynamically discover ser
1. Add the gRPC endpoint as a [link](./config/links.md) with type set to `Grpc`. This enables the GraphQL server to understand that the specified source is a gRPC endpoint that supports reflection.
- ```graphql
- schema
- @link(
- src: "https://my-grpc-service.com:50051"
- type: Grpc
- ) {
- query: Query
- }
+ ```yaml
+ links:
+ - src: "https://my-grpc-service.com:50051"
+ type: Grpc
```
2. Next, as before we will just add the methods with a fully qualified name:
diff --git a/docs/honey-comb.md b/docs/honey-comb.md
index 63d559f07a..781398fef9 100644
--- a/docs/honey-comb.md
+++ b/docs/honey-comb.md
@@ -9,27 +9,16 @@ sidebar_label: Honeycomb
2. Login to your account
3. Go to `Account -> Team Settings -> Environments and API Keys -> Configuration` and create new or copy existing api key
4. Go to your GraphQL configuration and update settings:
- ```graphql
- schema
- @telemetry(
- export: {
- otlp: {
- url: "https://api.honeycomb.io:443"
- headers: [
- {
- key: "x-honeycomb-team"
- value: "{{.env.HONEYCOMB_API_KEY}}"
- }
- {
- key: "x-honeycomb-dataset"
- value: ""
- }
- ]
- }
- }
- ) {
- query: Query
- }
+ ```yaml
+ telemetry:
+ export:
+ otlp:
+ url: "https://api.honeycomb.io:443"
+ headers:
+ - key: "x-honeycomb-team"
+ value: "{{.env.HONEYCOMB_API_KEY}}"
+ - key: "x-honeycomb-dataset"
+ value: ""
```
5. Set the api key you've copied before to the environment variable named `HONEYCOMB_API_KEY` and start tailcall with updated config
diff --git a/docs/http-cache.md b/docs/http-cache.md
index 9530ebca30..6c132eb452 100644
--- a/docs/http-cache.md
+++ b/docs/http-cache.md
@@ -11,22 +11,19 @@ HTTP Caching in Tailcall is designed to enhance performance and minimize the fre
HTTP Caching involves saving copies of HTTP responses to serve identical future requests directly from the cache, bypassing the need for new API calls. This reduces latency, conserves bandwidth, and alleviates the load on upstream services by utilizing a cache keyed by request URLs and headers.
-By default, HTTP caching is turned off in Tailcall. Enabling it requires setting the `httpCache` parameter to integer value which is greater than 0 in the `@upstream` configuration. Tailcall employs a in-memory _Least_Recently_Used_ (LRU) cache mechanism to manage stored responses, adhering to upstream-provided caching directives like `Cache-Control` to optimize the caching process and minimize redundant upstream API requests.
+By default, HTTP caching is turned off in Tailcall. Enabling it requires setting the `httpCache` parameter to integer value which is greater than 0 in the `upstream` configuration. Tailcall employs a in-memory _Least_Recently_Used_ (LRU) cache mechanism to manage stored responses, adhering to upstream-provided caching directives like `Cache-Control` to optimize the caching process and minimize redundant upstream API requests.
### Enabling HTTP Caching
To activate HTTP caching, adjust the upstream configuration in Tailcall by setting `httpCache` to appropriate cache size, as shown in the following example:
-```graphql
-schema
- @server(port: 4000)
- @upstream(
- # highlight-start
- httpCache: 42
- # highlight-end
- ) {
- query: Query
-}
+```yaml
+server:
+ port: 4000
+upstream:
+ # highlight-start
+ httpCache: 42
+ # highlight-end
```
This configuration instructs Tailcall to cache responses from the designated upstream API.
@@ -37,11 +34,9 @@ Enabling the `cacheControl` setting in Tailcall ensures that [Cache-Control] hea
Here is how you can enable the `cacheControl` setting within your Tailcall schema to apply these caching instructions:
-```graphql
-schema @server(headers: {cacheControl: true}) {
- query: Query
- mutation: Mutation
-}
+```yaml
+server:
+ cacheControl: true
```
[cache-control]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
diff --git a/docs/http2.md b/docs/http2.md
index fbe432dacd..c054b5df8c 100644
--- a/docs/http2.md
+++ b/docs/http2.md
@@ -5,6 +5,9 @@ slug: graphql-http2-guide-tailcall
sidebar_label: HTTP/2
---
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
[HTTP/2](https://www.cloudflare.com/en-in/learning/performance/http2-vs-http1.1/) represents a significant advancement in web protocols, offering enhancements such as multiplexing, header compression, and streamlined connection handling, all designed to improve web performance.
Tailcall enables support for HTTP/2 for both server (ingress) and client (egress) operations, facilitating the protocol's adoption for both incoming and outgoing server requests. For egress, there is no special setting that's required, Tailcall will automatically upgrade the connection to HTTP/2 whenever possible. To configure ingress properly, you need to provide the following settings
@@ -59,16 +62,25 @@ Use self-signed certificates for HTTP/2 configurations in development environmen
Once the certificate and key are generated we can link them with our main configuration using the [links](./config/links.md) configuration, to enable HTTPS.
-```graphql showLineNumbers
-schema
+
+
+
+```yaml
+links:
+ - src: main.graphql
#highlight-start
- @link(type: "Cert", src: "./cert.pem")
- @link(type: "Key", src: "./key.pem") {
+ - type: "Cert"
+ src: "./cert.pem"
+ - type: "Key"
+ src: "./key.pem"
#highlight-end
- query: Query
- mutation: Mutation
-}
+```
+
+
+
+
+```graphql showLineNumbers
type Query {
posts: [Post]
@http(url: "https://jsonplaceholder.typicode.com/posts")
@@ -80,19 +92,30 @@ type User {
}
```
+
+
+
Once HTTPS is enabled we set the version to `HTTP2` for the server:
-```graphql showLineNumbers
-schema
- @link(type: "Cert", src: "./cert.pem")
- @link(type: "Key", src: "./key.pem")
- #highlight-start
- @server(version: HTTP2) {
- #highlight-end
- query: Query
- mutation: Mutation
-}
+
+
+
+```yaml
+server:
+ version: HTTP2
+links:
+ - src: main.graphql
+ - type: Cert
+ src: ./cert.pem
+ - type: Key
+ src: ./key.pem
+```
+
+
+
+
+```graphql showLineNumbers
type Query {
posts: [Post]
@http(url: "https://jsonplaceholder.typicode.com/posts")
@@ -104,6 +127,9 @@ type User {
}
```
+
+
+
That's pretty much all that's required. Now you can go ahead and [launch](/docs/getting-started.mdx#starting-the-graphql-server) your server as usual.
```bash
diff --git a/docs/new-relic.md b/docs/new-relic.md
index 625eb908cb..d7e1920c77 100644
--- a/docs/new-relic.md
+++ b/docs/new-relic.md
@@ -11,23 +11,14 @@ The guide is based on [official doc](https://docs.newrelic.com/docs/more-integra
2. Login to your account
3. Go to ` -> Api Keys` and copy license value for key with access to write data
4. Go to GraphQL configuration and update it with:
- ```graphql
- schema
- @telemetry(
- export: {
- otlp: {
- url: "https://otlp.nr-data.net:4317"
- headers: [
- {
- key: "api-key"
- value: "{{.env.NEWRELIC_API_KEY}}"
- }
- ]
- }
- }
- ) {
- query: Query
- }
+ ```yaml
+ telemetry:
+ export:
+ otlp:
+ url: "https://otlp.nr-data.net:4317"
+ headers:
+ - key: "api-key"
+ value: "{{.env.NEWRELIC_API_KEY}}"
```
5. Set the api key you've copied before to the environment variable named `NEWRELIC_API_KEY` and start tailcall with updated config
diff --git a/docs/playground.md b/docs/playground.md
index 89b16a91f0..216ff340ef 100644
--- a/docs/playground.md
+++ b/docs/playground.md
@@ -1,19 +1,32 @@
---
title: GraphQL Playground
-description: "Explore and test server configurations with the @server directive's showcase feature in a controlled environment. Ideal for quick experimentation and learning with dynamic GraphQL schema configurations. Not recommended for production due to performance and security considerations."
+description: "Explore and test server configuration showcase feature in a controlled environment. Ideal for quick experimentation and learning with dynamic GraphQL schema configurations. Not recommended for production due to performance and security considerations."
slug: graphql-playground-guide
sidebar_label: GraphQL Playground
---
-The `@server` directive's `showcase` option allows for hands-on experimentation with server configurations in a controlled environment. This feature simplifies the process of exploring and testing different settings. This enables experimenting with random configurations hosted, without the need to restart the server or affect existing setups.
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+The `showcase` option of server configuration allows for hands-on experimentation with server configurations in a controlled environment. This feature simplifies the process of exploring and testing different settings. This enables experimenting with random configurations hosted, without the need to restart the server or affect existing setups.
#### Example Usage
-```graphql showLineNumbers
-schema @server(showcase: true) {
- query: Query
-}
+
+
+
+```yaml
+server:
+ showcase: true
+links:
+ - src: main.graphql
+```
+
+
+
+
+```graphql showLineNumbers
type User {
notId: Int
notName: String
@@ -27,6 +40,9 @@ type Query {
}
```
+
+
+
To test it out, append `/showcase/graphql?config=YOUR_CONFIG_URL` to your GraphQL base URL when querying the data.
![Showcase](/images/docs/showcase.png)
diff --git a/docs/rest.md b/docs/rest.md
index d84d7fa5ae..d972b7c1b9 100644
--- a/docs/rest.md
+++ b/docs/rest.md
@@ -81,15 +81,12 @@ to know more about the `@rest` directive, please refer to the [Tailcall GraphQL
### Step 3: Link the operation to the main config file
-checkout the `@link` directive in the config snippet below to link the operation file. This step is crucial to make the REST endpoint available.
+checkout the `links` option in the config snippet below to link the operation file. This step is crucial to make the REST endpoint available.
-```graphql
-schema
- #highlight-start
- @link(type: Operation, src: "user-operation.graphql") {
- #highlight-end
- query: Query
-}
+```yaml
+links:
+ - type: Operation
+ src: "user-operation.graphql"
```
To know more about the `links` configuration, please refer [it's documentation](./config/links.md).
diff --git a/docs/scalar.md b/docs/scalar.md
index ad6a621c3d..684a7a45e3 100644
--- a/docs/scalar.md
+++ b/docs/scalar.md
@@ -42,10 +42,6 @@ Apart from the pre-defined list of scalars, you can define your own custom scala
```graphql
scalar AnyScalar
-schema @server(port: 8000, hostname: "localhost") {
- query: Query
-}
-
type Query {
any(value: AnyScalar!): AnyScalar!
@expr(body: "{{.args.value}}")
@@ -61,10 +57,6 @@ Be aware that custom scalars don't have any validation and can be mapped to any
Let's try using these custom scalars in our GraphQL schema.
```graphql
-schema @server(port: 8000, hostname: "localhost") {
- query: Query
-}
-
type Query {
email(value: Email!): Email!
@expr(body: "{{.args.value}}")
diff --git a/docs/scripting.md b/docs/scripting.md
index 3d9bb9c3cd..5bb5aef70f 100644
--- a/docs/scripting.md
+++ b/docs/scripting.md
@@ -31,11 +31,12 @@ function foo({request}) {
Once you have a worker file ready, link that file to the GraphQL configuration using the [`links`](./config/links.md) configuration and define the [onRequest](./config/upstream.md#onrequest) property.
-```graphql
-schema
- @link(type: Script, src: "./worker.js")
- @upstream(onRequest: "foo") {
- query: Query
+```yaml
+upstream:
+ onRequest: foo
+links:
+ - type: Script
+ src: ./worker.js
}
```
diff --git a/docs/telemetry.md b/docs/telemetry.md
index 002fb2d8cf..85c8788a94 100644
--- a/docs/telemetry.md
+++ b/docs/telemetry.md
@@ -38,10 +38,6 @@ While [Apollo studio](./apollo-studio.md) telemetry also provides analytics tool
Consider we have the following GraphQL configuration that connects with jsonplaceholder.com to fetch the data about user and posts
```graphql
-schema @server(port: 8000, hostname: "0.0.0.0") {
- query: Query
-}
-
type Query {
posts: [Post]
@http(url: "http://jsonplaceholder.typicode.com/posts")
@@ -83,15 +79,11 @@ Telemetry configuration is provided by [`telemetry`](./config/telemetry.md) conf
To enable it we can update our config with something like config below:
-```graphql
-schema
- @telemetry(
- export: {
- otlp: {url: "http://your-otlp-compatible-backend.com"}
- }
- ) {
- query: Query
-}
+```yaml
+telemetry:
+ export:
+ otlp:
+ url: "http://your-otlp-compatible-backend.com"
```
Here, `export` specifies the format of generated data and endpoint to which to send that data. Continue reading to know more about different options for it.
diff --git a/graphql/graphql.md b/graphql/graphql.md
index 70c2312c87..23b1232d87 100644
--- a/graphql/graphql.md
+++ b/graphql/graphql.md
@@ -257,7 +257,6 @@ type Query {
In this example:
We have used the `@http` directive to attach resolvers to the `post` field in the `Query`.
-and `@upstream` directive to define the base URL for the upstream server.
This configuration is enough for starting a GraphQL server using Tailcall. You can start the server using the [`start`](/docs/tailcall-graphql-cli/#start) command.
diff --git a/graphql/introspection.md b/graphql/introspection.md
index 60ebcb7b9b..d0d91bb6e6 100644
--- a/graphql/introspection.md
+++ b/graphql/introspection.md
@@ -80,11 +80,9 @@ Introspection allows the creation of smart clients that can adapt to schema chan
Most GraphQL servers have introspection enabled by default. However, it is crucial to ensure that this feature is properly configured and secured, especially in production environments. Here is an example of enabling introspection in Tailcall GraphQL server configuration:
-```graphql showLineNumbers
-schema @server(introspection: true) {
- query: Query
- mutation: Mutation
-}
+```yaml showLineNumbers
+server:
+ introspection: true
```
### Security Considerations
diff --git a/src/components/home/Configuration.tsx b/src/components/home/Configuration.tsx
index 69bc9cd3fd..bcd40ea40d 100644
--- a/src/components/home/Configuration.tsx
+++ b/src/components/home/Configuration.tsx
@@ -47,12 +47,7 @@ const CodeTabItem = ({code, language}: {code: string; language: "json" | "yaml"
export default Configuration
-const GRAPHQL_CONFIG = `schema
- @server(port: 8000) {
- query: Query
-}
-
-type Query {
+const GRAPHQL_CONFIG = `type Query {
users: [User] @http(url: "http://jsonplaceholder.typicode.com/users")
posts: [Post] @http(url: "http://jsonplaceholder.typicode.com/posts")
}