System Configuration

The System section controls the core runtime behaviour of Synentra, including the HTTP/HTTPS server configuration (Kestrel), database and cache storage backends, request rate limiting, and circuit breaker policies. These settings define how the gateway handles network connections, persists data, manages performance limits, and protects against service failures.

---

Server

Controls the Kestrel web server.

Property	Type	Default	Description
System.Http.Port	int	7080	Port used by the HTTP listener.
System.Https.Enabled	bool	false	Enables the HTTPS listener using the configured TLS certificate.
System.Https.Port	int	7443	Port used by the HTTPS listener.
System.Https.Certificate.Path	string	—	Path to the TLS certificate file in PFX or PEM format.
System.Https.Certificate.Password	string	—	Password for the certificate, if required. Leave empty for passwordless certificates.
System.MaxConcurrentConnections	long	null	Maximum number of simultaneous client connections. null allows unlimited connections.
System.MaxConcurrentUpgradedConnections	long	null	Maximum number of concurrent upgraded connections, such as WebSocket or HTTP/2 connections. null allows unlimited connections.
System.KeepAliveTimeout	TimeSpan?	00:02:00	Maximum idle time before an inactive keep-alive connection is closed.
System.RequestHeadersTimeout	TimeSpan	00:00:30	Maximum time allowed for a client to send the complete request headers.
System.MaxRequestBodySizeMb	int?	50	Maximum allowed request body size, in megabytes. Set to null to remove the limit.

HTTPS Example

{
  "System": {
    "Server": {
      "Http": { "Port": 7080 },
      "Https": {
        "Enabled": true,
        "Port": 7443,
        "Certificate": {
          "Path": "/certs/synentra.pfx",
          "Password": "s3cr3t"
        }
      },
      "MaxConcurrentConnections": 1000,
      "MaxConcurrentUpgradedConnections": 1000,
      "KeepAliveTimeout": "00:02:00",
      "RequestHeadersTimeout": "00:00:30",
      "MaxRequestBodySizeMb": 50
    }
  }
}

note

HTTP and HTTPS ports must be different. Synentra will throw an InvalidOperationException at startup if they match.

---

Storage

Database

Property	Type	Default	Description
DefaultProvider	string	"Sqlite"	Active database provider. Supported values are Sqlite and Postgres.
Providers.Sqlite.ConnectionString	string	—	Connection string used to connect to the SQLite database. Typically specifies the database file location (for example, Data Source=synentra.db).
Providers.Postgres.ConnectionString	string	—	Connection string used to connect to a PostgreSQL database, including the host, port, database name, and authentication credentials.

{
  "System": {
    "Database": {
      "DefaultProvider": "Sqlite",
      "Providers": {
        "Sqlite": { "ConnectionString": "Data Source=synentra.db" }
      }
    }
  }
}

Cache

Property	Type	Default	Description
DefaultProvider	string	"Memory"	Active cache provider. Supported values are "Memory" and "Redis".
Providers.Memory	object	{}	Configuration for the in-memory cache provider.
Providers.Memory.TimeToLive	TimeSpan	1.00:00:00	Default time-to-live (TTL) for cached entries stored in memory.
Providers.Redis.Endpoint	string	—	Redis server endpoint in the format host:port (for example, localhost:6379).
Providers.Redis.TimeToLive	TimeSpan	1.00:00:00	Default time-to-live (TTL) for cached entries stored in Redis.
Providers.Redis.AbortOnConnectFail	bool	false	Determines whether initialization fails immediately if the initial connection to Redis cannot be established. When false, the client automatically retries connecting in the background.
Providers.Redis.ConnectRetry	int	5	Number of times to retry the initial connection before giving up.
Providers.Redis.ConnectTimeout	TimeSpan	00:00:05	Maximum time to wait when establishing a connection to the Redis server before the attempt times out.

{
  "System": {
    "Cache": {
      "DefaultProvider": "Memory",
      "Providers": {
        "Redis": {
          "Endpoint": "localhost:6379",
          "TimeToLive": "1.00:00:00",
          "AbortOnConnectFail": false,
          "ConnectRetry": 5,
          "ConnectTimeout": "00:00:05"
        },
        "Memory": {
          "TimeToLive": "1.00:00:00"
        }
      }
    }
  }
}

---

Rate Limiting

Per-agent token-bucket rate limiter.

Property	Type	Default	Description
Enabled	bool	true	Enables or disables rate limiting globally. When disabled, no rate limits are enforced for any agent.
DefaultRequestsPerMinute	int	60	Default maximum number of requests an agent can make per minute. This limit applies unless a different rate limit is configured for the specific agent.

Agents that exceed the limit receive a 429 Too Many Requests response with a Retry-After: 60 header.

{
  "System": {
    "RateLimit": {
      "Enabled": true,
      "DefaultRequestsPerMinute": 60
      }
  }
}

---

Circuit Breaker

Protects upstream services from repeated failures.

Property	Type	Default	Description
Enabled	bool	true	Enables or disables the circuit breaker globally. When disabled, failed requests are not tracked and circuit state transitions are not applied.
FailureThreshold	int	5	Number of consecutive or accumulated failures within the sampling window required before the circuit transitions to the open state.
OpenDurationSeconds	int	30	Amount of time, in seconds, that the circuit remains open before allowing requests again to test service recovery.
SamplingWindowSeconds	int	60	Time window, in seconds, used to evaluate failures and determine whether the failure threshold has been reached.

When the circuit is open, requests receive a 503 Service Unavailable response.

{
  "System": {
    "CircuitBreaker": {
      "Enabled": true,
      "FailureThreshold": 3,
      "OpenDurationSeconds": 30,
      "SamplingWindowSeconds": 60
    }
  }
}