Gateway

Set gateway server settings in this section:

[gateway]
timeout = "30s"
subgraph_timeout = "4s"

• timeout: Timeout for slow requests and responses. Default: 30s.
• subgraph_timeout: A global timeout for all subgraph requests. A subgraph can override this setting.

Read more about rate limiting. You can hot-reload the limit and duration settings.

[gateway.rate_limit]
storage = "memory"

• storage: Rate limit storage backend. Supported values: memory, redis.

Set global rate limits for all subgraphs:

[gateway.rate_limit.global]
limit = 100
duration = "10s"

• limit: Maximum number of requests allowed in the duration.
• duration: Time window for the limit.

[gateway.rate_limit.redis]
url = "redis://localhost:6379"
key_prefix = "my_gateway"

• url: Redis server URL.
• key_prefix: Prefix for the rate limit keys.

To connect using TLS, the Redis URL must start with rediss://. If the server CA certificate is not in the system certificates or if you want to use mTLS, define paths to these files in the TLS configuration.

[gateway.rate_limit.redis.tls]
cert = "/path/to/user.crt"
key = "/path/to/user.key"
ca = "/path/to/ca.crt"

• cert: Path to the client certificate.
• key: Path to the client key.
• ca: Path to the CA certificate.

Configure query batching in the Grafbase Gateway. When you use a large batch of queries, you risk causing a denial of service attack on your subgraph service or gateway.

[gateway.batching]
enabled = true
limit = 5

• enabled: Enables query batching. Defaults to false.
• limit: The maximum number of queries in a batch. If not set, the gateway does not limit the number of queries in a batch.

Use retry configuration to specify how to handle subgraph request failures. A subgraph request can fail when the service times out, returns an error code, or reaches its rate limit.

[gateway.retry]
enabled = true
min_per_second = 10
ttl = "1s"
retry_percent = 0.1
retry_mutations = false

The gateway uses budget logic for retries. A successful subgraph request adds to the budget, while a failing request uses budget capacity.

• enabled: Enables retries for the given subgraph. Defaults to false.
• min_per_second: How many retries are available per second, at a minimum. Defaults to 10.
• ttl: Each successful request to the subgraph adds to the retry budget. This setting controls how long the budget remembers successful requests. Defaults to 10s.
• retry_percent: The fraction of the successful requests budget that can be used for retries. Defaults to 0.2.
• retry_mutations: Whether mutations should be retried at all. Enable this setting only if mutations are idempotent. Defaults to false.

When you enable subgraph retries, the gateway executes them with an exponential backoff. The gateway performs the first retry after 100 milliseconds, the second after 200 milliseconds, the third after 400 milliseconds, and so on. The engine adds jitter to the times to prevent the thundering herd problem where too many requests reach the subgraph simultaneously. The gateway applies a jitter multiplier between 0.0 to 2.0 to the retry backoff.

Read more about access logs to implement the required hooks.

[gateway.access_logs]
enabled = true
path = "/path/to/logs"
rotate = "daily"
mode = "blocking"

• enabled: Enables the access log writer.
• path: Specifies the log directory.
• rotate: Defines a rotation strategy, after which a new log file is created, and the previous one gets archived; options include never, minutely, hourly, or daily.
• rotate.size: Defines a size-based rotation strategy. The value is in bytes; the log file rotates when it reaches or exceeds this limit.
• mode: Specifies how the system behaves when the log queue is full and the writer can't write to the file quickly enough. Options include blocking, which blocks the caller, or non_blocking, which returns an error while sending the data back to the caller.

The system names the current log file access.log and saves it to the path you specify. When you enable rotation, the system maintains access.log as the current file and adds timestamp suffixes to archived files. The timestamp indicates when the logger begins writing to each file.