Runtime Configuration

Overview

GQLForge’s runtime behavior is controlled through directives applied to the schema definition in your GraphQL configuration. These directives govern how the server listens for connections, how it communicates with upstream services, and how it integrates with external systems.

Core Directives

@server

Controls the GraphQL server’s runtime settings.

schema @server(port: 8000, hostname: "0.0.0.0") {
  query: Query
}

Common options:

OptionTypeDefaultDescription
portInt8000Port the server listens on
hostnameString"127.0.0.1"Network interface to bind to
workersInt(auto)Number of worker threads
globalResponseTimeoutInt—Maximum response time in milliseconds

@upstream

Configures defaults for all outbound HTTP connections to upstream services.

schema
@server(port: 8000)
@upstream(
  baseURL: "https://jsonplaceholder.typicode.com"
  httpCache: 42
) {
  query: Query
}

Common options:

OptionTypeDefaultDescription
baseURLString—Base URL prepended to all relative resolver paths
httpCacheInt—Cache TTL in seconds for upstream responses
connectTimeoutInt—Connection timeout in milliseconds
timeoutInt—Request timeout in milliseconds
proxyString—HTTP proxy URL for outbound requests

Imports external files into the configuration. Supports multiple file types.

schema @server(port: 8000) @link(type: Config, src: "./users.graphql") @link(type: Protobuf, src: "./service.proto") {
  query: Query
}
OptionTypeDescription
typeLinkTypeType of the linked resource (Config, Protobuf, Script, etc.)
srcStringPath to the external file
idStringOptional identifier for referencing in other directives

Telemetry

GQLForge supports telemetry export for observability. Configure tracing and metrics through the @telemetry directive:

schema @server(port: 8000) @telemetry(export: { otlp: { url: "http://localhost:4317" } }) {
  query: Query
}

This sends traces and metrics to an OpenTelemetry collector. The telemetry data includes resolver execution times, upstream request durations, and error rates.

Combining Directives

Multiple directives are applied together on the schema definition:

schema
@server(port: 8000, hostname: "0.0.0.0")
@upstream(baseURL: "https://api.example.com", httpCache: 60)
@link(type: Config, src: "./types.graphql")
@telemetry(export: { otlp: { url: "http://localhost:4317" } }) {
  query: Query
  mutation: Mutation
}

Further Reading