@link

The @link directive is defined as follows:

Directive Definition

Directive Definition
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 @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.

How it Works

The @link directive requires specifying a source src, the resource's type type, and an optional identifier id.

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)
type: This specifies the link's type, which determines how the imported resource is integrated into the schema. For a list of supported types, see the Supported Types section.
id: This is an optional field that assigns a unique identifier to the link. It's helpful for referring to the link within the schema.
headers: This is an optional field that assigns custom headers to the gRPC reflection server requests. Specifying a key-value map of header names and their values achieves this. (Values supports Mustache template)
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.

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.

schema
  @server(port: 8000)
  @upstream(httpCache: 42, batch: {delay: 10})
  @link(
    id: "news"
    src: "./src/grpc/news.proto"
    type: Protobuf
    headers: [{key: "authorization", value: "Bearer 123"}]
  ) {
  query: Query
}

type Query {
  news: NewsData!
    @grpc(method: "news.NewsService.GetAllNews")
}

type News {
  id: Int
  title: String
  body: String
  postImage: String
}

type NewsData {
  news: [News]!
}

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.

schema
  @server(port: 8000)
  @upstream(httpCache: 42, batch: {delay: 10})
  @link(
    id: "news"
    src: "{{.env.NEWS_PROTO_PATH}}"
    type: Protobuf
    headers: [
      {key: "authorization", value: "{{.env.BEARER}}"}
    ]
  ) {
  query: Query
}

type Query {
  news: NewsData!
    @grpc(method: "news.NewsService.GetAllNews")
}

type News {
  id: Int
  title: String
  body: String
  postImage: String
}

type NewsData {
  news: [News]!
}

In the above example, you can notice that src is changed to src: "{{.env.NEWS_PROTO_PATH}}" and value for auth is changed to value: "{{.env.BEARER}}".

Assuming BEARER="Bearer 123" and NEWS_PROTO_PATH=./src/grpc/news.proto is set as your environment variables, the parsed config will automatically parse the mustache templates 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:

Config

The Config link type is essential for importing other configuration files. This feature enables a modular approach to schema management by allowing configurations from the imported file to override overlapping settings in the main schema. This functionality is useful in large projects, where maintaining a single monolithic schema file becomes impractical. By using Config, developers can split their schema configurations into manageable pieces, thus promoting better organization and scalability.

Example use case:

Modularizing schema configurations for different environments (development, staging, production).
Reusing common configurations across multiple schema files.

Protobuf

The Protobuf link type integrates Protocol Buffers definitions by importing .proto files. This integration is crucial for Tailcall to communicate with gRPC services. By including .proto definitions, the GraphQL server can directly interact with gRPC services, allowing for efficient and type-safe communication.

For detailed integration steps and best practices, refer to the gRPC Integration Guide.

Script

The Script link type allows the config to link to an external JavaScript file. This file can contain custom logic that is executed in response to HTTP request-response events. This feature enables developers to implement custom behaviors, such as adding headers to responses or filtering requests based on specific criteria.

Example script for adding a custom header to all outgoing requests:

function onRequest({request}) {
  // Add a custom header for all outgoing requests
  request.headers["X-Custom-Header"] = "Processed"

  // Return the updated request
  return {request}
}

Cert

The Cert link type is designed for importing SSL/TLS certificates, a crucial component for enabling HTTPS in your GraphQL server. This link type ensures that the server can expose connections over HTTPS.

tip

When using the Cert link type, specify the path to the certificate file. Ensure the certificate is up-to-date and issued by a trusted certificate authority (CA) to avoid security warnings or connection issues.

Example use case:

Securing communication between the GraphQL server and clients.
- Enhancing privacy and security by encrypting data in transit.

Key

The Key link type imports the private key associated with your SSL/TLS certificate, enabling HTTPS for your GraphQL server. The private key is a critical security element that decrypts information encrypted by the corresponding public key in the SSL/TLS certificate.

When configuring the Key link type, provide the path to your private key file. Ensure the private key matches the imported certificate specified by the Cert link above, and is protected by appropriate file permissions to maintain security.

Operation

The Operation link type connects your schema to a set of predefined, GraphQL spec-compliant queries and mutations. This functionality allows for the validation and optimization of these operations by the GraphQL server.

Each type serves a specific purpose, enabling the flexible integration of external resources into your GraphQL schema.

Htpasswd

The Htpasswd link type allows the importation of an htpasswd file. This file is utilized to set up Basic authentication.

Jwks

The Jwks link type enables the importation of a JWKS file. This file facilitates the provision of detailed access control through JWT authentication.

Grpc

The Grpc link type enables the GraphQL server to understand that the specified source is a gRPC endpoint that supports reflection.

How it Works​

Example​

Example using Mustache template​

Supported Types​

Config​

Protobuf​

Script​

Cert​

Key​

Operation​

Htpasswd​

Jwks​

Grpc​