Documentation v1.0.0
Home GitHub

Architecture

This page shows the go-ip-sentry layers in one diagram and lists each layer's responsibility and the cross-cutting rules.

System Overview

graph TB
    REQ[HTTP Request] --> MW[Middleware<br/>GinMiddleware / HTTPMiddleware]
    MW --> CHK[IPGuardian.Check]
    CHK --> DEV[Device Identification<br/>IP / UA / Session / Fingerprint]
    DEV --> MGR[List Management<br/>Allow / Deny / Block]
    CHK --> SCORE[Dynamic Scoring<br/>Four Dimensions in Parallel]
    SCORE --> GEO[GeoLite2]
    DEV & MGR & SCORE <--> REDIS[(Redis)]
    MGR --> FILE[(List JSON Files)]
    MGR --> SMTP[SMTP Notification]
    CHK --> RES[IPGuardianResult]
    RES --> MW

Layers

Layer Source Responsibility
Middleware middleware.go Wires Check into Gin or net/http and writes a JSON error on failure
Check flow instance.go Creates the instance, applies rate-limit defaults, then runs list checks, scoring, and rate limits in order
Device identification device.go Resolves client IP, User-Agent, the HMAC-signed session, and the device fingerprint, with list status and per-minute counts
Dynamic scoring score.go Four goroutines (correlation, geo, behavior, fingerprint) compute in parallel and merge into a 0–100 score
Geo detection geo.go GeoLite2 lookups, a 24-hour cache, and risk checks over the location history
List management allow.go / deny.go / block.go Permanent Allow/Deny lists (Redis plus JSON file) and temporary Block (Redis TTL)
Types and constants type.go Config, Parameter, Redis key templates, private CIDRs

Cross-Cutting Rules

Rule Implementation
All state lives in Redis Counters, sets, lists, and the geo cache sit in Redis; an instance only keeps Allow/Deny memory caches, so instances sharing one Redis share decisions
Allow beats everything Check tests Trust first and skips blocking, scoring, and rate limits on a hit
Lazy defaults Most Parameter defaults are not set in New() but written back into Config on each request; see Known Issues
Scores stay internal Check returns only IPGuardianResult; scores and triggered flags are not exposed

Further Reading

中文