fastrag.serve.config#

Frozen configuration for fastrag.serve.create_app().

Classes

ServeConfig(*, allowed_origins[, ...])

Configuration for the serving app.
class fastrag.serve.config.ServeConfig(*, allowed_origins, cookie_secure=True, cookie_domain=None, session_ttl_days=30, expiry_bump_min_days=1, max_request_bytes=32768, max_content_chars=4000, max_messages_per_chat=200, max_chats_per_session=100, generation_timeout_s=120.0, keepalive_interval_s=15.0, log_level='INFO', bearer_tokens=False, metrics_enabled=True, metrics_token=None, trust_proxy_headers=False, rate_limiting_enabled=False, rate_limit_generation='10/minute', rate_limit_read='60/minute', rate_limit_new_session='20/hour', geoip_database_path=None)[source]#

Bases: object

Configuration for the serving app.

Frozen and keyword-only. Nothing under src/fastrag/ reads os.environ — the caller reads the environment and passes the result in, exactly as 08_sources.py already does for the chat model. Fail fast rather than start in a degraded state: every field is validated in __post_init__, raising ConfigurationError earlier than startup, at the line that got it wrong.

Parameters:

  • allowed_origins (list[str]) – Origins allowed by CORS. The one required field, with no default. A "*" wildcard is rejected: credentialed requests cannot use Access-Control-Allow-Origin: *. The app configures CORS from this list itself, so create_app() callers never add their own CORSMiddleware.

  • cookie_secure (bool) – Whether the session cookie carries the Secure flag.

  • cookie_domain (str | None) – Optional Domain for the session cookie.

  • session_ttl_days (int) – Days a session (and its chats) live without activity.

  • expiry_bump_min_days (int) – Minimum headroom before an expiry bump is written.

  • max_request_bytes (int) – Reject a request body larger than this with 413.

  • max_content_chars (int) – Reject a content longer than this with 422.

  • max_messages_per_chat (int) – Cap on messages per chat (422 beyond).

  • max_chats_per_session (int) – Cap on chats per session (422 beyond).

  • generation_timeout_s (float) – End-to-end budget (retrieval + generation) per generation; a timeout lands as TIMEOUT.

  • keepalive_interval_s (float) – Seconds between SSE keep-alive comments, and between pings on the chat’s lock connection while it answers. Keep it below the idle timeout of any proxy in front of the app or of Postgres.

  • log_level (str) – Root logger level for the JSON log output.

  • bearer_tokens (bool) – Enable the bearer-token path and POST /v1/sessions. Off by default — see “Bearer tokens, in full” in the serving design notes.

  • metrics_enabled (bool) – Whether GET /metrics is mounted at all. On by default; every series is still collected when this is False, only the route that exposes them is withheld.

  • metrics_token (str | None) – Optional bearer token guarding GET /metrics. None (the default) leaves the endpoint unguarded — reasonable for a scrape target reachable only from inside a private network. When set, a request without a matching Authorization: Bearer header gets 401 and no metric text.

  • trust_proxy_headers (bool) – Whether the leftmost entry of an incoming X-Forwarded-For header is trusted as the real client IP, instead of request.client.host. Off by default: this stack usually runs behind a reverse proxy, but trusting a client-settable header unconditionally is a trivial rate-limit and audit-log bypass. Turn this on only when a proxy in front of this app is known to set (and not merely pass through) the header.

  • rate_limiting_enabled (bool) – Whether the three limits below are enforced at all. Off by default, so an existing caller or the test suite is unaffected until it opts in.

  • rate_limit_generation (str) – Limit on POST /v1/chats, POST /v1/chats/{id}/messages, and POST /v1/chats/{id}/messages/{mid}, as a "10/minute"-style string (<count>/<second|minute|hour|day>), per client IP.

  • rate_limit_read (str) – Limit on GET /v1/chats and GET /v1/chats/{id}, same format, per client IP.

  • rate_limit_new_session (str) – Limit on the branch of a request that mints a new session (POST /v1/chats and POST /v1/sessions when neither presents a live session), same format, per client IP — not a limit on those endpoints as a whole, which rate_limit_generation already covers for POST /v1/chats.

  • geoip_database_path (Path | None) – Path to a MaxMind GeoLite2-Country .mmdb file, for resolving a session’s country. None (the default) disables country resolution entirely; nothing is downloaded or vendored by this package — see the serving guide for where to get one. Requires the geoip extra (geoip2); without it, country resolution is silently unavailable even when a path is set.

allowed_origins: list[str]#
cookie_secure: bool = True#
cookie_domain: str | None = None#
session_ttl_days: int = 30#
expiry_bump_min_days: int = 1#
max_request_bytes: int = 32768#
max_content_chars: int = 4000#
max_messages_per_chat: int = 200#
max_chats_per_session: int = 100#
generation_timeout_s: float = 120.0#
keepalive_interval_s: float = 15.0#
log_level: str = 'INFO'#
bearer_tokens: bool = False#
metrics_enabled: bool = True#
metrics_token: str | None = None#
trust_proxy_headers: bool = False#
rate_limiting_enabled: bool = False#
rate_limit_generation: str = '10/minute'#
rate_limit_read: str = '60/minute'#
rate_limit_new_session: str = '20/hour'#
geoip_database_path: Path | None = None#