Skip to content
Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

broker

broker is basebox' GraphQL HTTP(s) server. Your client sends GraphQL requests to the broker's /graphql endpoint, e.g. https://broker.host.com/graphql.

The broker's tasks are:

  • Authorize and authenticate GraphQL requests
  • Validate GraphQL requests
  • Make sure the user is allowed to perform an operation
  • Communicate with the dbproxy to resolve requests
  • Communicate with an optional microservice
  • Return GraphQL compliant JSON response

Running the broker

In production, the broker should be run as a system service; we will provide instructions on how to achieve this soon. For now, since basebox is not yet production ready, you run broker simply in a terminal.

Command Line Parameters

To see broker's command line arguments, call it with --help:

❯ ./broker --help

This is broker, basebox' universal high performance GraphQL server.

Usage: broker [OPTIONS]

Options:
  -c, --config-file <CONFIG_FILE>
          Path and file name of the configuration file

  -d, --dump-default-config
          Dump default config file to stdout and quit

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

So to run broker, you create the config file (see below) and start broker like so:

./broker -c /path/to/broker-config.toml

Example Configuration File

Most of broker's options are controlled by a TOML configuration file. You can get the default configuration file and use it as a starter for your own configuration by running broker with the -d switch; so to create a config file template, just run:

./broker -d > config.toml

This will create a file named config.toml in the current directory with the default configuration.

Here is the current version:

[generic]
# log level; can be error, warn, info, debug, trace
log_level = "info"

[graphql]
# path and file name to GraphQL schema file
schema_file = "/path/to/schema.gql"
# allow introspection is off by default
allow_introspection = false

[proxy]
# host name or IP of basebox DB proxy
host = "127.0.0.1"
port = 8081
# Whether to use http or https to connect to the proxy
tls = false

[server]
# Host name or IP address of the network interface broker should listen on for requests.
# Use "0.0.0.0" for all interfaces, an IP address for a specific interface or
# "127.0.0.1" for local requests.
host = "127.0.0.1"

# Port number; default is 80 for http, 443 for https
port = 8080

# number of HTTP server threads to spawn; default is one per CPU core
# workers = 2

# Maximum allowed HTTP request size in bytes; default is 256k
# max_request_size = 262144

# Path and file name of TLS/SSL key file
# tls_key_file = "/path/to/key.pem"

# Path and file name of TLS certificate (chain) file
# tls_cert_file = "/path/to/cert.pem"

[auth]
# Key stores can be configured either via URL (in several ways, see below), or
# by using a local file. Local file configuration prevents network requests,
# thus facilitating strongly firewalled deployments. It can also help in a
# containerized scenario where the IdP issuer field might conflict between
# frontend/client and backend(s):
# From a user point of view, broker and IdP might both be running on `localhost`
# (or any other network hostname), but inside the container network the IdP is
# reachable only under its container name (e.g. `idp` or `keycloak`).
# While this can be mitigated by manually editing hosts files or deploying a
# DNS, file-based key store configuration is more straightforward.
#
# To populate a local key store file, simply download the JWKS data from your IdP, e.g.
# https://idp.example.com/realms/testing/protocol/openid-connect/certs
#
# jwks_file = "/path/to/certs.json"

# URL of IdP's discovery endpoint. If not set, the URL is made up by appending
# ".well-known/openid-configuration" to the `iss` field.
# discovery_url = "https://idp.example.com/realms/testing/.well-known/openid-configuration"

# URL of IdP's public keystore. If set, the discovery endpoint is not used at all.
# jwks_url = "https://idp.example.com/realms/testing/protocol/openid-connect/certs"

# Access token validation:
# Contents of 'iss' field, usually the URL of the authentication realm
# iss = "https://idp.example.com/realms/testing"

# Contents of the 'aud' field for access tokens; for Keycloak, this defaults to 'account';
# for Auth0, this is the value of the Default Audience field in your Tenant settings.
# aud = "account"


# [auth_management]
# If you want to use the Auth Management API, please configure it here by providing the
# "auth_management" section. This is optional.

# Currently, we provide support for Auth0; Keycloak is coming soon.
# provider = "auth0"

# The domain of your Auth0 realm
# domain = "your-tenant.auth0.com"

# Client ID of the machine-to-machine client that is allowed to get access tokens
# for the Management API
# https://auth0.com/docs/secure/tokens/access-tokens/get-management-api-access-tokens-for-production
# client_id = "your-client-id"

# Client secret of the machine-to-machine client that is allowed to get access tokens
# for the Management API
# client_secret = "your-client-secret"

More on the configuration options can be found in broker's reference.