dev.server.toml

# (C) 2024 GoodData Corporation
[server]

#######################################################################
# Flight RPC Setup
#######################################################################

# host to bind Flight RPC server to. Default is 127.0.0.1 - listening on
# localhost only.
#
# use:
#
# - 0.0.0.0 - to bind to all addressed = reachable via network
# - 127.0.0.1 - to bind to localhost only (unreachable via outside network)
# - custom address to bind to
#
listen_host = "127.0.0.1"

# port on which the Flight RPC server should listen
listen_port = 17001

# host name to use when sending this server's Flight RPC location to clients.
# Defaults to current hostname.
#
# Advertising different host from the one that the server is bound to is
# often needed in Dockerized environments.
#
# ---
#
# Example: you run the server inside Docker on localhost and have port forwarding
# setup. You want to access the server from your workstation. In this setup,
# the 'listen_host' is set to "0.0.0.0" (server listens on all interfaces within
# the container) and the 'advertise_host' is set to "localhost".
#
# When you make a GetFlightInfo call to the server (running inside docker), it will
# generate a Flight accordingly and the returned Locations will again point at
# "localhost" so the subsequent DoGet call goes again to the Dockerized server.
#
# Without the 'advertise_host', the GetFlightInfo would return Location referencing
# some internal / randomly assigned hostname that is unreachable from your workstation.
advertise_host = "127.0.0.1"

# port number to use when sending this server's Flight RPC location to clients.
# Defaults to value of 'listen_port'.
#
# Advertising different port from the one that the server is listening is often
# needed in environments where port forwarding is in effect.
#
# ---
#
# Example: you run multiple servers inside Docker on localhost and have port
# forwarding setup. Each server goes to different port.
#
# Analogous to the host example (see above), the Dockerized server needs to send
# location with port number that can be reached from your workstation.
advertise_port = 17001

#######################################################################
# TLS Setup
#######################################################################

# optionally specify to use TLS; default when not specified is False
#
# IMPORTANT: when you turn on TLS, you must also specify at minimum
# the TLS certificate and TLS private key for the server to use.
# Additionally, if you use self-signed certificates, you need to
# also specify the tls_root_certificate.
use_tls = false

# if you want to use TLS (see 'use_tls' above), then you must specify
# server's certificate.
#
# This is supposed to be a PEM encoded X.509 certificate identifying
# your server.
#
# You can inline the certificate value into this setting, or you can
# specify file where the certificate resides.
#
# To specify certificate file, code the value of this setting as
# '@/absolute/path/to/cert`
# tls_certificate = "..."

# if you want to use TLS (see 'use_tls' above), then you must specify
# the server's private key.
#
# This is supposed to be PEM encoded X.509 private key. Similar to
# the certificate, you can also use the '@/absolute/path/to/cert'
# notation to make server load the certificate from some file.
#
# IMPORTANT: never commit config files containing inlined secrets
# such as the private key into VCS. You can leverage the server's
# ability to combine config from multiple files: have one file
# without secrets and commit that to VCS if you so desire. The other
# config file with secrets should be outside of VCS.
# tls_private_key = "..."

# if you use mTLS and have self-signed certificates, then you must
# also include the X.509 certificate of your CA that signed them.
#
# Again, you can inline the certificate in PEM encoding right here
# into this setting, or you can use the '@/absolute/path/to/ca-cert'
# notation.
# tls_root_certificate = "..."

#######################################################################
# Task Handling
#######################################################################

# number of threads available for tasks which generate flights or
# flight listing. Default is 32.
#
# Each GetFlightInfo request that generates a flight delegates this
# to a task. The task executes in a thread pool of this size.
task_threads = 32

#######################################################################
# Server Infrastructure & Maintenance
#######################################################################

# host to bind prometheus metrics endpoint; disabled by default
#
# use:
#
# - 0.0.0.0 - to bind to all addressed
# - 127.0.0.1 - to bind to localhost only (unreachable via outside network)
# - custom address to bind to
#
# if not specified, the prometheus metrics endpoint will not be started
# metrics_host = "0.0.0.0"

# port for prometheus metrics endpoint; default is 17101
#
# will only be used if `metrics_host` is specified
# metrics_port = 17101

# host to bind health check endpoint; disabled by default
#
# use:
#
# - 0.0.0.0 - to bind to all addressed
# - 127.0.0.1 - to bind to localhost only (unreachable via outside network)
# - custom address to bind to
#
# if not specified, the health check endpoint will not be started
# health_check_host = "0.0.0.0"

# port for health check endpoint; default is 8877
#
# will only be used if `health_check_host` is specified
# health_check_port = 8877

# optionally specify interval, in seconds, of calls to malloc_trim - this
# helps to release unused memory back to the system. Default is 30 seconds.
#
# especially useful in memory constrained and memory-limited environments.
malloc_trim_interval_sec = 30

# optionally specify key name under which the log event name should appear
# in the structured logs. Default is 'event'
#
# you may want to override this in case you want to align the event's key
# name with the rest of your environment
log_event_key_name = "event"

# optionally specify mapping for telemetry (tracing) key names that will appear
# in structured logs. by default, server writes trace information into 'trace_id',
# 'span_id' and 'parent_span_id'
#
# you may want to override these in case you want to align those logs key names
# with the rest of your enviornment
log_trace_keys = { "trace_id" = "trace_id", "span_id" = "span_id", "parent_span_id" = "parent_span_id" }

# optionally enable exports of OpenTelemetry tracing. Default is no exports
# which also means most of the tracing code and instrumentation will be noop.
#
# Allowed values are: zipkin, otlp-grpc, otlp-http or console (for debug)
#
# IMPORTANT: If you want to enable the trace exports, you must install one
# the appropriate OpenTelemetry exporter package yourself and then configure
# the exporter using the appropriate environment variables (these are typically
# documented by the exporter)
otel_exporter_type = "none"

# optionally specify OpenTelemetry service name to associate with the server's
# resource.
#
# If you do not specify the service name, then the tracing infrastructure and
# instrumentation will be no-op.
#
# IMPORTANT: if you want to enable and export OpenTelemetry tracing, then you
# must specify both the `otel_exporter_type` and this option.
# otel_service_name = "your-service-name"

# optionally specify OpenTelemetry namespace to associate with this server's resource.
#
# Default is no namespace.
# otel_service_namespace = "your-namespace"

# optionally specify OpenTelemetry service instance id to associate with this server's
# resource.
#
# Usually, this is a unique identifier of the running server instance. In environments
# such as k8s, you typically want to associate the instance id to pod name. In other
# environments, it may be the hostname.
#
# Default is to use current hostname.
# otel_service_instance_id = "your-service-instance-id"

# optionally specify whether OpenTelemetry integration within the server should look
# for, extract and use an OpenTelemetry context coming through the Flight RPC
# request headers.
#
# When this option is enabled, the code will use OpenTelemetry's context
# propagation `extract` method to obtain the context from Flight RPC request headers. This
# context will then be used when creating OpenTelemetry span representing the Flight
# RPC call.
#
# In simple words:
#
# - IF your server is configured to export traces to same backend where your server's clients
#   also export their traces AND the clients inject the trace context into the Flight RPC headers,
#   THEN you will be able to correlate all calls under one trace ID.
#
# - ELSE, you should keep this turned off; each Flight RPC request to your server will create
#   a new trace ID.
#
# Default is false.
# otel_extract_context = false

#######################################################################
# Authentication configuration
#######################################################################

# specify authentication method to use. can be one of 'none' or 'token'.
#
# if you do not include this option, then the server will not do
# any authentication. This is dangerous if your server is listening
# on interfaces that are reachable from the public network.
#
# if you specify the 'token' method, then the default strategy
# for verifying tokens is the 'EnumeratedTokenVerification'. For this
# to work, you need to specify one or more valid tokens that the
# client is expected to send. See the end of this file on how to
# do this.
#
# Alternatively, you can implement your own strategy for verifying
# tokens. See the option below.
authentication_method = "none"

# Specify strategy to use for verifying tokens.
#
# The default strategy is 'EnumeratedTokenVerification' which expects
# that client sends a token that is included in a list of allowed
# tokens. See the end of this file for example how to define those
# tokens.
#
# To implement your own token verification strategy, you need to
# implement your own subclass of 'TokenVerificationStrategy' and
# then modify this setting to provide module name that contains
# that implementation.
#
# For example if the full path to class implementing your strategy
# is my_server.auth.custom.MyCustomStrategy, then the value
# of the 'token_verification' should be 'my_server.auth.custom'.
#
# Upon startup, the server will try to dynamically import and
# load your implementation of TokenVerificationStrategy from the
# specified module.
# token_verification = "EnumeratedTokenVerification"

# Optionally specify header name that is expected to carry the
# token.
#
# If not specified, the token is expected to come in a HTTP-like
# convention: the 'authorization' header (must be lower-case) and
# the value of 'Bearer <token>' where <token> is the value token
# itself.
# token_header_name = "x-custom-header-with-token"