From 23162b7d4a3e24ebe3af9557616c73978f0dfa5f Mon Sep 17 00:00:00 2001 From: meskill <8974488+meskill@users.noreply.github.com> Date: Mon, 16 Dec 2024 17:24:31 +0000 Subject: [PATCH] move runtime directives to config folder --- docs/{directives/link.md => config/links.md} | 181 ++++++++----------- docs/{directives => config}/server.md | 0 docs/{directives => config}/telemetry.md | 0 docs/{directives => config}/upstream.md | 0 sidebars.ts | 15 +- 5 files changed, 88 insertions(+), 108 deletions(-) rename docs/{directives/link.md => config/links.md} (65%) rename docs/{directives => config}/server.md (100%) rename docs/{directives => config}/telemetry.md (100%) rename docs/{directives => config}/upstream.md (100%) diff --git a/docs/directives/link.md b/docs/config/links.md similarity index 65% rename from docs/directives/link.md rename to docs/config/links.md index 60149dfee..e4de1a79c 100644 --- a/docs/directives/link.md +++ b/docs/config/links.md @@ -1,55 +1,26 @@ --- -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!] -) 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="Link Configuration" showLineNumbers +link: + - src: "path_or_url_of_external_resource" + type: "LinkType" + id: "optional_identifier" + headers: + - key: "header_key" + value: "header_value" ``` -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) @@ -61,35 +32,30 @@ The `@link` directive requires specifying a source `src`, the resource's type `t ### Linking other configs -With `@link` you can link other [configuration files](#config) that will be merged with the root configuration i.e. the first config file you've specified for the cli. - -See in details how it works: +With `links` you can link [schema files](#config) that will be merged together. -- The definitions `@server`, `@upstream`, `@telemetry`, `@links` are used only from the root configuration and their definitions from the linked configs are ignored -- 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) +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: -Root config: +```yaml title="Runtime Config" +server: + port: 8000 -```graphql -schema - @server(port: 8000) - @upstream(httpCache: 10, batch: {delay: 10}) - @link(src: "a.graphql", type: Config) - @link(src: "b.graphql", type: Config) { - query: Query -} -``` +upstream: + httpCache: 10 + batch: + delay: 10 -a.graphql: +links: + - src: a.graphql + type: Config + - src: b.graphql + type: Config +``` -```graphql -schema - # this definitions are ignored from linked config - @server(port: 3000) - @upstream(httpCache: 42, batch: {delay: 22}) - @link(src: "nested.graphql", type: Config) { +```graphql title="a.graphql" +schema { query: Query } @@ -106,13 +72,8 @@ type Query { } ``` -b.graphql: - -```graphql -schema - # this definitions are ignored from linked config - @server(port: 4000) - @upstream(httpCache: 33, batch: {delay: 48}) { +```graphql title="b.graphql" +schema { query: Query } @@ -134,14 +95,6 @@ type User { The merged result config will look like this: ```graphql -schema - @server(port: 8000) - @upstream(batch: {delay: 10, headers: []}, httpCache: 10) - @link(src: "a.graphql", type: Config) - @link(src: "b.graphql", type: Config) { - query: Query -} - union Media = Book | Movie | Podcast type Query { @@ -162,18 +115,31 @@ type User { ## 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. + +```yaml title="config.yaml" +server: + port: 8000 -```graphql showLineNumbers -schema - @server(port: 8000) - @upstream(httpCache: 42, batch: {delay: 10}) - @link( - id: "news" +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 } @@ -196,23 +162,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. -```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: "{{.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") @@ -239,7 +212,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 diff --git a/docs/directives/server.md b/docs/config/server.md similarity index 100% rename from docs/directives/server.md rename to docs/config/server.md diff --git a/docs/directives/telemetry.md b/docs/config/telemetry.md similarity index 100% rename from docs/directives/telemetry.md rename to docs/config/telemetry.md diff --git a/docs/directives/upstream.md b/docs/config/upstream.md similarity index 100% rename from docs/directives/upstream.md rename to docs/config/upstream.md diff --git a/sidebars.ts b/sidebars.ts index 78097bba9..c608fc40b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -20,6 +20,17 @@ const sidebars: SidebarsConfig = { collapsed: false, items: ["getting-started", "cli", "context", "playground", "conventions", "execution-strategy", "watch-mode"], }, + { + type: "category", + label: "Config", + collapsed: false, + items: [ + "config/link", + "config/server", + "config/telemetry", + "config/upstream" + ].sort() + }, { type: "category", label: "Directives", @@ -34,14 +45,10 @@ const sidebars: SidebarsConfig = { "directives/grpc", "directives/http", "directives/js", - "directives/link", "directives/modify", "directives/omit", "directives/protected", "directives/rest", - "directives/server", - "directives/telemetry", - "directives/upstream", "directives/discriminate", ].sort(), },