Key Components

Application class

Flasgo is the core application object. It owns HTTP and WebSocket routing, route-aware CORS, lifespan, process state, middleware, settings, templates, static assets, testing, optional internal endpoints, and the development server entrypoint.

Common methods include:

• route, get, post, put, patch, delete
• websocket, add_websocket_route, lifespan, state
• before_request, after_request, errorhandler
• register_auth_backend, authorize
• ratelimit, resolve_outbound_url, aresolve_outbound_url
• configure_templates, render_template, render_template_async
• configure_static, test_client
• openapi_spec, run
• register_blueprint, url_for, policy_snapshot, override_dependencies

Request and response primitives

Component	Role
Request	Access method, path, headers, query params, JSON, and form data
Response	Build explicit HTTP responses with case-insensitive headers, validated cookies, redirects, JSON, and templated output
FormData	Read parsed form values and uploaded files
UploadedFile	Represents an uploaded file from multipart form handling
Body, Query, Header, Cookie, Form	Bind and validate typed request data through Annotated
Depends	Resolves and caches returned or yielded provider values with request/function lifetimes
ValidationIssue	Describes one bounded request validation failure
RequestValidationError	Carries structured request binding failures
FormValidationError	Adds parsed FormData for explicit form redisplay handling
HTTPException	Raises an HTTP error with an explicit status, detail, and optional headers
WebSocket	Accepts, receives, sends, iterates, denies, and closes WebSocket connections
WebSocketDisconnect	Reports a peer disconnect and its close code
BackgroundTasks	Runs best-effort tasks after complete response delivery and request dependency cleanup

Globals and helpers

Flasgo exposes a few framework conveniences for request-time access:

Helper	Purpose
request	Access the current request
session	Access the current session mapping from the configured backend
url_for	Generate validated URLs using the active request application and mount path
current_user	Access the authenticated user context
jsonify	Return JSON from lightweight handlers
redirect	Create redirect responses quickly
is_safe_redirect_target	Vet request-controlled relative same-origin redirect destinations
abort	Raise structured HTTP errors; annotated -> Never for type checkers

Authentication and authorization

Component	Role
User and AuthResult	Carry the authenticated identity and optional challenge
bearer_token_backend	Adapts a sync or async token validator into an auth backend
extract_bearer_token	Strictly extracts a configured bearer scheme
jwt_backend	Builds a strict optional HS256 authentication backend
encode_jwt	Creates a short-lived token matching that backend contract
AllowAny	Allows anonymous and authenticated users
IsAuthenticated	Requires an authenticated user
HasScope	Requires one named user scope

Custom permission objects and sync or async permission callables are also supported.

Routing style

Flasgo uses Flask-style decorators and path converters.

from flasgo import Flasgo

app = Flasgo()


@app.get("/posts/<int:post_id>")
async def show_post(post_id: int):
    return {"post_id": post_id}

Supported converter patterns include <name>, <int:name>, <float:name>, and <path:name>. An untyped <name> segment is converted to the handler’s annotated type. Pass HTTP methods as a collection such as methods=["POST"]; a single string raises TypeError. Repeated parameter names, unknown converters, malformed placeholders such as <int: id>, and duplicate explicit route names raise ValueError at registration.

Supporting subsystems

Subsystem	Role
Settings	Loads known configuration from mappings, modules, objects, or a Settings instance
CORSConfig	Defines an exact-origin application or per-route browser access policy
SessionSigner	Signs client-side session cookies with HMAC-SHA256
SSRFGuard	Validates outbound URLs, blocks private networks by default, and pins resolved addresses
RateLimiter	Applies in-process sliding-window limits for security failures or route-level quotas
JinjaTemplates	Renders templates through a sandboxed Jinja environment; render_async() serves templates configured with enable_async=True
TestClient	Exercises HTTP, cookies, forms, files, lifespan, and WebSockets without a network socket
configure_logging	Configures bounded text or JSON events for the flasgo logger hierarchy
flasgo[metrics] subsystem	Records optional per-process Prometheus metrics behind bearer authentication
app.metrics_registry	Read-only access to the app-local Prometheus registry, or None when metrics are disabled (0.9.1+)
flasgo[otel] subsystem	Traces HTTP and WebSocket work and exports through OTLP/HTTP
Flasgo.openapi_spec	Generates OpenAPI 3.2 data with JSON Schema 2020-12

Route-level rate limits are attached with app.ratelimit(...) or the exported rate_limit decorator. The built-in security-failure limiter is separate and handles repeated host, CSRF, and authentication/authorization failures, including protected docs and metrics endpoints.

Route composition, streaming, and shared storage

Flasgo 0.9.0 provides these additional exports and methods:

Component	Role
Blueprint	Nested HTTP route groups with additive permissions, dependencies, and quotas
ResponseValidationError	Safe server-side failure when an explicit response contract is violated
StreamingResponse	Bounded async bytes/text with transport backpressure and disconnect cleanup
EventSourceResponse, ServerSentEvent	JSON-encoded SSE data, validated event metadata, and heartbeats
NDJSONResponse	Bounded JSON values emitted one per line
RedisStore	Async Redis/Valkey storage with bounded operations and atomic updates
RedisRateLimiter	Shared sliding-window quotas for decorated HTTP/WebSocket routes
ServerSideSessions	Opaque-cookie sessions with rotation, revocation, and stale-write detection
MemoryStore	Bounded process-local session storage for tests and development
StoreUnavailable	Backend availability failure, handled as 503 by the framework
Session.regenerate, Session.session_id	Request rotation on save and read the current server-side identifier
TestClient.astream, AsyncTestStream	Read HTTP streams incrementally in an async test context

See the 0.9.0 feature overview for installation and focused guides. Session.session_id is a credential and must not be logged or exposed in responses.

CLI

The flasgo command exposes run, routes, openapi, check, and optional Alembic-backed db commands. See CLI and Migrations for examples.

Supporting public types

The package also exports the types needed for extension and precise testing:

• Settings and Session
• RateLimitRule
• SSRFConfig, SSRFGuard, SSRFResolvedURL, and SSRFViolation
• CORSConfig and is_safe_redirect_target
• WebSocketException, WebSocketHandshakeError, SyncWebSocketSession, and AsyncWebSocketSession
• TestResponse and AsyncTestStream
• FlasgoJSONFormatter
• Body, Query, Header, Cookie, Form, and Depends
• ValidationIssue, RequestValidationError, and FormValidationError
• BaseLoader, SecureTemplateLoader, Template, and TemplateNotFound
• create_template_environment and standalone render_template

Sources:

• README.md
• flasgo/__init__.py