Documentation
¶
Index ¶
- Constants
- func AddStatusRoute(app *echolib.Echo, engine *guardcore.Engine, path string) error
- func AgentStats(engine *guardcore.Engine) map[string]any
- func GuardWebSocket(engine *guardcore.Engine, c *echolib.Context) *guardcore.WebSocketCloseReason
- func MarkInitialized(engine *guardcore.Engine)
- func New(engine *guardcore.Engine, opts ...Option) (echolib.MiddlewareFunc, error)
- func NewStatusHandler(engine *guardcore.Engine) (echolib.HandlerFunc, error)
- func RefreshCloudIPRanges(engine *guardcore.Engine) error
- func Reset(engine *guardcore.Engine)
- func WebSocketHTTPStatus(reason *guardcore.WebSocketCloseReason) int
- func WithRouteID(ctx context.Context, routeID string) context.Context
- type ComponentStatus
- type InitializationStatus
- type Option
- type RedisStatus
Constants ¶
const DefaultMaxBodyBytes int64 = 262144
const DefaultStatusPath = "/_guard/status"
DefaultStatusPath is the route path add_status_route registers by default (the reference's /_guard/status).
Variables ¶
This section is empty.
Functions ¶
func AddStatusRoute ¶
AddStatusRoute registers the status handler on the echo instance at path (the empty string picks DefaultStatusPath), mirroring fastapi-guard add_status_route:
if err := echo.AddStatusRoute(app, engine, ""); err != nil { ... }
The method-scoped route answers GET only; other methods fall through to the framework's not-found handling.
func AgentStats ¶
AgentStats mirrors the reference agent_stats property: agentless answers {"enabled": false, "degraded": <degraded>}; a wired handler answers {"enabled": true, "degraded": false} merged with its AgentStats() dict when it provides the stats surface.
func GuardWebSocket ¶
GuardWebSocket runs the engine's websocket handshake checks over the upgrade request: identity resolution, the fail-secure unknown-address close, the ban check, the is_ip_allowed verdict, the ws rate limit, and the penetration detection pass sharing the HTTP pipeline's suspicious counts. A nil result allows the upgrade; a non-nil reason closes it. A nil engine fails closed with the security-check-failed reason.
func MarkInitialized ¶
MarkInitialized marks the engine initialized without running the startup I/O (the reference mark_initialized: a stack warmed externally tells the middleware to consider itself initialized); a later engine.Initialize becomes a no-op.
func NewStatusHandler ¶
func NewStatusHandler(engine *guardcore.Engine) (echolib.HandlerFunc, error)
NewStatusHandler returns the echo handler serving the engine's initialization status JSON (the reference guard_initialization_status). Mount it behind the security middleware like any other route and exclude it from the checks via the config's path exclusions when it should answer unguarded.
func RefreshCloudIPRanges ¶
RefreshCloudIPRanges refreshes the blocked cloud providers' ranges on demand (the reference refresh_cloud_ip_ranges): with redis configured the refresh runs through the redis-backed store at the configured TTL (the reference cloud_handler.refresh_async), otherwise in memory (the reference cloud_handler.refresh). A config without blocked providers is a no-op, exactly like the reference early return.
func Reset ¶
Reset drops the rate limiter's state (the reference reset, which awaits rate_limit_handler.reset): the redis sliding windows and the in-memory fallback counters.
func WebSocketHTTPStatus ¶
func WebSocketHTTPStatus(reason *guardcore.WebSocketCloseReason) int
WebSocketHTTPStatus maps a close reason onto the HTTP status an upgrade rejection carries: 503 for the try-again-later security-check failure, 403 for every policy-violation reason, 200 for a nil (allowed) verdict.
Types ¶
type ComponentStatus ¶
type ComponentStatus struct {
Ready bool `json:"ready"`
LastRefreshed *time.Time `json:"last_refreshed"`
Entries int `json:"entries"`
}
ComponentStatus is one cloud provider's row of the reference cloud_handler.get_status payload.
type InitializationStatus ¶
type InitializationStatus struct {
CloudProviders map[string]ComponentStatus `json:"cloud_providers"`
GeoIP map[string]any `json:"geo_ip"`
Redis RedisStatus `json:"redis"`
}
InitializationStatus is the JSON payload the status route serves.
func GetInitializationStatus ¶
func GetInitializationStatus(engine *guardcore.Engine) (InitializationStatus, error)
GetInitializationStatus snapshots the engine's initialization surface (the reference get_initialization_status serving the handler initializer's payload): the cloud-provider table, the geo-ip snapshot and the redis probe. AddStatusRoute serves the same payload over HTTP.
type RedisStatus ¶
type RedisStatus struct {
Enabled bool `json:"enabled"`
OK bool `json:"ok"`
Error *string `json:"error"`
}
RedisStatus is the redis component of the status payload: whether the engine was configured with redis, and - when it was - whether the manager answers a probe right now. ok defaults true when redis is disabled (there is nothing to be down), mirroring the PHP siblings' initialize() snapshot.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
advanced_app/cmd/server
command
Command server assembles the advanced example: tuned engine config, the engine's route registry, echo route groups, the echo-guard middleware, and graceful shutdown.
|
Command server assembles the advanced example: tuned engine config, the engine's route registry, echo route groups, the echo-guard middleware, and graceful shutdown. |
|
advanced_app/internal/config
Package config builds the engine's SecurityConfig from environment variables with production-oriented defaults.
|
Package config builds the engine's SecurityConfig from environment variables with production-oriented defaults. |
|
advanced_app/internal/routes
Package routes holds the HTTP handlers of the advanced example, split by concern the way the Python advanced example splits routers.
|
Package routes holds the HTTP handlers of the advanced example, split by concern the way the Python advanced example splits routers. |
|
simple_app
command
Command simple_app is a minimal guarded Echo server.
|
Command simple_app is a minimal guarded Echo server. |