docs: refactor to runtime configuration (#571)

* docs: explain how linked config are merged

* move runtime directives to config folder

* migrate documentation to runtime config

* fix references

* add introduction doc to runtime configuration

docs/N+1.md

@@ -176,7 +176,7 @@ If you run the query, at first you will observe a lot of duplicate requests are
 
 ![Duplicate Upstream Calls](../static/images/docs/n+1-duplicate.png)
 
-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](./directives/server.md).
+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

docs/apollo-federation-subgraph.md

@@ -40,7 +40,7 @@ Please, note that you don't need to specify the `@key` directive manually when d
 
 ## Enable federation in the Tailcall config
 
-Federation is controlled by the flag [`enableFederation`](./directives/server.md#enablefederation). Define it with `true` value to enable federation support.
+Federation is controlled by the flag [`enableFederation`](./config/server.md#enablefederation). Define it with `true` value to enable federation support.
 
 ## Register your subgraph
 

docs/apollo-studio.md

@@ -34,7 +34,7 @@ This guide illustrates how to configure `tailcall` to send usage metrics to [Apo
 
       ![local-schema.png](../static/images/apollo-studio/local-schema.png)
 
-You have now created a Monolith graph in Apollo Studio. The next step is to configure `tailcall` to use the `APOLLO_API_KEY` and `APOLLO_GRAPH_REF`. Follow detailed instructions [here](./directives/telemetry.md).
+You have now created a Monolith graph in Apollo Studio. The next step is to configure `tailcall` to use the `APOLLO_API_KEY` and `APOLLO_GRAPH_REF`. Follow detailed instructions [here](./config/telemetry.md).
 
 ## Checking the metrics in Apollo Studio
 

docs/auth.md

@@ -46,7 +46,7 @@ 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](./directives/link.md) connect multiple authentication files as you need for different provides. To connect it use either [`Htpasswd`](./directives/link.md#htpasswd) or [`Jwks`](./directives/link.md#jwks) link type
+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
 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:
@@ -250,7 +250,7 @@ In case you linked multiple authentication files all of them will be used to exe
 
 ### Authentication headers
 
-To validate authentication for user request the specific headers are used (like `Authorization` header). In case auth is enabled for tailcall those headers will be also added to the [`allowedHeaders` list](./directives/upstream.md#allowedheaders) and therefore they will be forwarded to the upstream requests implicitly.
+To validate authentication for user request the specific headers are used (like `Authorization` header). In case auth is enabled for tailcall those headers will be also added to the [`allowedHeaders` list](./config/upstream.md#allowedheaders) and therefore they will be forwarded to the upstream requests implicitly.
 
 ## Basic Authentication
 
@@ -270,7 +270,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](./directives/link.md#htpasswd).
+To use Basic Auth you should first include htpasswd file generated from [Prerequisites](#prerequisites) with the help of [`@link` directive](./config/links.md#htpasswd).
 
 We can use that file as an example for it that has data for `testuser:mypassword` credentials in encrypted format:
 
@@ -353,7 +353,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](./directives/link.md#jwks).
+To use JWT you should first include JWKS file generated from [Prerequisites](#prerequisites) with the help of [`@link` directive](./config/links.md#jwks).
 
 We can use that file as an example for it:
 

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`](./directives/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 directive 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.

docs/directives/link.md → docs/config/links.md

@@ -1,60 +1,28 @@
 ---
-title: "@link"
-description: The @link directive is used for bringing external resources into your GraphQL schema.
-slug: ../link-directive
+title: "links"
+description: The links configuration is used for bringing external resources into your GraphQL schema.
+slug: ../links-config
 ---
 
-The `@link` directive is defined as follows:
-
-```graphql title="Directive Definition" showLineNumbers
-directive @link(
-  """
-  Source path or URL of the external resource
-  """
-  src: String!
-
-  """
-  Type of the external resource
-  """
-  type: LinkType!
-
-  """
-  Optional identifier for the link
-  """
-  id: String
-
-  """
-  Optional headers for gRPC reflection server requests
-  """
-  headers: [InputKeyValue!]
-
-  """
-  Optional directories to search for imported proto files.
-  """
-  proto_paths: [String!]
-) on SCHEMA
-
-"""
-Available types for external resources
-"""
-enum LinkType {
-  Config
-  Protobuf
-  Script
-  Cert
-  Key
-  Operation
-  Htpasswd
-  Jwks
-  Grpc
-}
+The `links` configuration is defined in a YAML file as follows:
+
+```yaml title="Runtime Configuration" showLineNumbers
+links:
+  - src: "path_or_url_of_external_resource"
+    type: "LinkType"
+    id: "optional_identifier"
+    headers:
+      - key: "header_key"
+        value: "header_value"
+    protoPaths:
+      - "path to proto"
 ```
 
-The `@link` directive is used for bringing external resources into your GraphQL schema. It makes it easier to include configurations, .proto files for gRPC services, and other files into your schema. With this directive, external resources are either merged with or used effectively in the importing configuration.
+The `links` configuration is used for bringing external resources into your GraphQL schema. It makes it easier to include configurations, .proto files for gRPC services, and other files into your schema. With this configuration, external resources are either merged with or used effectively in the importing configuration.
 
 ## How it Works
 
-The `@link` directive requires specifying a source `src`, the resource's type `type`, and an optional identifier `id`.
+The `links` configuration requires specifying a source `src`, the resource's type `type`, and an optional identifier `id` for every entry:
 
 - `src`: The source of the link is defined here. It can be either a URL or a file path. When a file path is given, it's relative to the file's location that is importing the link. (This field also supports Mustache template)
 
@@ -66,20 +34,116 @@ The `@link` directive requires specifying a source `src`, the resource's type `t
 
 - `proto_paths`: This is an optional field that specifies additional directories to search for imported proto files. It only takes effect when `type` is `Protobuf`.
 
+### Linking other configs
+
+With `links` you can link [schema files](#config) that will be merged together.
+
+The schema definitions (i.e. types, unions, enums) are merged by the [federation composition rules](https://www.apollographql.com/docs/graphos/reference/federation/composition-rules)
+
+For example, consider the following files:
+
+```yaml title="Runtime Config"
+server:
+  port: 8000
+
+upstream:
+  httpCache: 10
+  batch:
+    delay: 10
+
+links:
+  - src: a.graphql
+    type: Config
+  - src: b.graphql
+    type: Config
+```
+
+```graphql title="a.graphql"
+schema {
+  query: Query
+}
+
+type User {
+  id: Int
+  age: Int
+}
+
+union Media = Book | Movie
+
+type Query {
+  media: media
+    @http(url: "http://jsonplaceholder.typicode.com/media")
+}
+```
+
+```graphql title="b.graphql"
+schema {
+  query: Query
+}
+
+type Query {
+  user(id: Int!): User
+    @http(
+      url: "http://jsonplaceholder.typicode.com/users/{{.args.id}}"
+    )
+}
+
+union Media = Book | Podcast
+
+type User {
+  id: Int
+  name: String
+}
+```
+
+The merged result config will look like this:
+
+```graphql
+union Media = Book | Movie | Podcast
+
+type Query {
+  media: Foo
+    @http(url: "http://jsonplaceholder.typicode.com/media")
+  post(id: Int!): Post
+    @http(
+      url: "http://jsonplaceholder.typicode.com/users/{{.args.id}}"
+    )
+}
+
+type User {
+  id: Int
+  age: Int
+  name: String
+}
+```
+
 ## Example
 
-The following example illustrates how to utilize the `@link` directive to incorporate a Protocol Buffers (.proto) file for a gRPC service into your GraphQL schema.
+The following example illustrates how to utilize the `links` configuration to incorporate a Protocol Buffers (.proto) file for a gRPC service into your GraphQL schema.
 
-```graphql showLineNumbers
-schema
-  @server(port: 8000)
-  @upstream(httpCache: 42, batch: {delay: 10})
-  @link(
-    id: "news"
+```yaml title="config.yaml"
+server:
+  port: 8000
+
+upstream:
+  httpCache: 10
+  batch:
+    delay: 10
+
+links:
+  - id: schema
+    src: schema.graphql
+    type: Config
+  - id: news
     src: "./src/grpc/news.proto"
     type: Protobuf
-    headers: [{key: "authorization", value: "Bearer 123"}]
-  ) {
+    headers:
+      - key: authorization
+        value: Bearer 123
+```
+
+```graphql title="schema.graphql" showLineNumbers
+schema {
   query: Query
 }
 
@@ -102,23 +166,30 @@ type NewsData {
 
 ## Example using Mustache template
 
-The following example illustrates how to utilize the `@link` directive to incorporate a Protocol Buffers (.proto) file for a gRPC service into your GraphQL schema using Mustache template.
+The following example illustrates how to utilize the `links` configuration to incorporate a Protocol Buffers (.proto) file for a gRPC service into your GraphQL schema using Mustache template.
+
+```yaml title="config.yaml"
+server:
+  port: 8000
+
+upstream:
+  httpCache: 10
+  batch:
+    delay: 10
 
-```graphql showLineNumbers
-schema
-  @server(port: 8000)
-  @upstream(httpCache: 42, batch: {delay: 10})
-  @link(
-    id: "news"
+links:
+  - id: schema
+    src: schema.graphql
+    type: Config
+  - id: news
     src: "{{.env.NEWS_PROTO_PATH}}"
     type: Protobuf
-    headers: [
-      {key: "authorization", value: "{{.env.BEARER}}"}
-    ]
-  ) {
-  query: Query
-}
+    headers:
+      - key: authorization
+        value: "{{.env.BEARER}}"
+```
 
+```graphql title="schema.graphql" showLineNumbers
 type Query {
   news: NewsData!
     @grpc(method: "news.NewsService.GetAllNews")
@@ -145,7 +216,7 @@ and populate it with the values given.
 
 ## Supported Types
 
-The `@link` directive enriches your configuration by supporting the integration of external resources. Each link type is designed to serve a specific purpose, enhancing the functionality and flexibility of your schema. Below is a detailed overview of each supported link type:
+The `links` configuration enriches your configuration by supporting the integration of external resources. Each link type is designed to serve a specific purpose, enhancing the functionality and flexibility of your schema. Below is a detailed overview of each supported link type:
 
 ### Config