2. Configuration Guide

🏁 Overview

This guide covers:

• 📥 Loading your config
• 🗂️ Configuration file structure
• 🔍 Plugin types
• 🔌 Declaring plugins
• ⚙️ Plugin attributes
• 🔄 Hot-reload with SIGHUP
• 💡 Example configurations

---

📥 Loading Your Configuration

Load your YAML config via command-line or environment variable, and apply changes at runtime with SIGHUP.

1.1 Command-Line Flag

easyrest-server --config /path/to/config.yaml

1.2 Environment Variable

export ER_CONFIG_FILE="/path/to/config.yaml"
easyrest-server

On SIGHUP (e.g. kill -SIGHUP $(pidof easyrest-server)), EasyREST re-reads all YAML files, updates server and plugins, and continues serving without downtime.

---

🗂️ Configuration File Structure

Your config.yaml has these top-level sections:

# 1. Server Settings
port:              8080
default_timezone:  "UTC"
access_log:        false
check_scope:       true
token_secret:      "your-jwt-secret"
token_user_search: "sub"

# 2. Anon Claims (optional)
anon_claims:
  scope: "public-read"
  role:  "guest"

# 3. CORS (optional)
cors:
  enabled: true
  origins: ["*"]
  methods: ["GET","POST","PATCH","DELETE","OPTIONS"]
  headers: ["Content-Type","Authorization"]
  max_age: 3600

# 4. TLS (optional)
tls_enabled:  false
tls_cert_file: "/path/to/cert.pem"
tls_key_file:  "/path/to/key.pem"

# 5. OTEL Tracing (optional)
otel:
  enabled:      true
  endpoint:     "http://otel-collector:4317"
  protocol:     "otlphttp"   # "otlp", "otlphttp", or "zipkin"
  service_name: "easyrest-server"

# 6. Server Tunables (optional)
server:
  read_timeout:                    "5s"
  write_timeout:                   "10s"
  idle_timeout:                    "2m"
  max_header_bytes:                1048576
  max_body_size:                   "10MB"
  http2_max_concurrent_streams:    100
  http2_max_read_frame_size:       1048576
  http2_idle_timeout:              "1m"

# 7. Plugin Settings
dirs:                          # External plugin files
  - ./plugins/db.yaml
  - ./plugins/cache.yaml
plugins:                       # Inline definitions
  sqlite_test:
    uri: "sqlite://./data/test.db"
  mysql_main:
    uri:         "mysql://user:pass@host:3306/main"
    enable_cache: true
    cache_name:  mysql_cache
  redis_cache:
    uri: "redis://cache:6379/0"

1️⃣ Server Settings: HTTP port, JWT, logging, scope checks 2️⃣ Anon Claims: default claims for unauthenticated access 3️⃣ CORS & TLS: cross-origin and HTTPS 4️⃣ OTEL Tracing: metrics and traces 5️⃣ Server Tunables: HTTP/2 performance options 6️⃣ Plugin Settings: file-based or inline definitions

---

🔍 Plugin Types

Role	Interface	Provided by Plugin
DBPlugin	easyrest.DBPlugin	SQLite, MySQL, PostgreSQL
CachePlugin	easyrest.CachePlugin	SQLite, MySQL, PostgreSQL, Redis

Note: SQLite/MySQL/PostgreSQL plugins support both DB and cache; Redis plugin is cache-only.

---

🔌 Declaring Plugins

4.1 Inline Definitions

plugins:
  postgres_main:
    uri:          "postgres://user:pass@host:5433/db?sslmode=disable"
    title:        "Primary Postgres"
    enable_cache: true            # ETag support
    cache_name:   postgres_cache  # Link to cache plugin
    db_tx_end:    "commit-allow-override"  # Transaction mode
    public:
      table: ["public_view"]
    exclude:
      table: ["internal_logs"]
    anon_claims:
      role: "guest"

• uri: plugin selection based on scheme
• title: optional API documentation title
• enable_cache: HTTP ETag caching
• cache_name: reference to a CachePlugin
• db_tx_end: commit vs rollback behavior
• public/exclude: table/function access control
• anon_claims: default JWT claims for anonymous users

4.2 External Plugin Files

plugins/db.yaml

- name: orders
  uri: "sqlite:///data/orders.db"
  enable_cache: true
  cache_name: orders_cache
  db_tx_end: "rollback"

plugins/cache.yaml

- name: orders_cache
  uri:  "redis://cache:6379/0"

Include in config.yaml:

plugin_configs:
  - plugins/db.yaml
  - plugins/cache.yaml

---

⚙️ Plugin Attributes Reference

Attribute	Type	Default	Description
name	string	inline key	API path identifier (/api/{name}/...)
uri	string	—	Connection scheme and details
path	string (opt.)	binary lookup	Custom plugin binary path
title	string (opt.)	EasyREST API	Swagger section title
enable_cache	boolean (opt.)	false	Enable ETag caching
cache_name	string (opt.)	same as name	Name of CachePlugin to use
db_tx_end	string (opt.)	"commit"	commit, rollback, commit-allow-override, rollback-allow-override
cache_invalidation_map	map[string][]string	—	RPC-to-table ETag invalidation mapping
public	AccessConfig	—	{table: [...], func: [...]} for public access
exclude	AccessConfig	—	{table: [...], func: [...]} to hide
anon_claims	map[string]any	—	Default JWT claims for anonymous requests
default_limit	int (opt.)	global default_limit	Per-endpoint default pagination limit

---

🔄 Hot-reloading with SIGHUP

kill -SIGHUP $(pidof easyrest-server)

On SIGHUP, EasyREST:

• Re-reads all config files and environment variables
• Applies OTEL, Server, and AnonClaims settings
• Starts, stops, or reconfigures plugin instances
• Continues serving without downtime

---

💡 Example Configurations

7.1 Single-file Inline Plugins

port: 8080
token_secret: "secret"
default_timezone: "America/Los_Angeles"

anon_claims:
  role: "guest"

otel:
  enabled: true
  endpoint: "http://otel:4317"
  protocol: "otlp"
  service_name: "my-easyrest"

server:
  read_timeout: "5s"
  write_timeout: "15s"
  max_body_size: "50MB"

plugins:
  postgres_main:
    uri: "postgres://user:pass@host:5433/db?sslmode=disable"
    enable_cache: true
    cache_name: postgres_cache
    db_tx_end: "commit-allow-override"

  redis_cache:
    uri: "redis://cache:6379/0"

7.2 Split Config & External Files

config.yaml

port: 8080
token_secret: "secret"

plugin_configs:
  - plugins/db.yaml
  - plugins/cache.yaml

plugins/db.yaml

---
- name: mysql_main
  uri: "mysql://user:pass@host:3306/main"
  enable_cache: true
  cache_name: mysql_cache
  db_tx_end: "rollback-allow-override"
---
- name: sqlite_test
  uri: "sqlite:///data/test.db"

plugins/cache.yaml

---
- name: mysql_cache
  uri: "mysql://user:pass@host:3306/main"
---
- name: redis_cache
  uri: "redis://cache:6379/0"

Reload with SIGHUP:

kill -SIGHUP $(pidof easyrest-server)