Documentation v1.0.0
Home GitHub

API Reference

This page lists every exported function, method, and type in package golangIPSentry, and marks which types are for internal use only.

Lifecycle

Function Signature Description
New func New(c Config) (*IPGuardian, error) Applies Log/Redis defaults, creates the logger, connects and pings Redis, builds the three list managers and loads list files, opens GeoLite2
IPGuardian.Close func (i *IPGuardian) Close() error Closes Redis, GeoLite2, and the logger; if closing Redis fails it returns that error without closing the rest

New fails when the logger cannot initialize or the Redis ping fails. List-file and GeoLite2 failures are only logged and never fail New.

Check and Integration

Method Signature Description
IPGuardian.Check func (i *IPGuardian) Check(r *http.Request, w http.ResponseWriter) IPGuardianResult The full decision flow; see Request Lifecycle
IPGuardian.HTTPMiddleware func (i *IPGuardian) HTTPMiddleware(next http.Handler) http.Handler net/http middleware
IPGuardian.GinMiddleware func (i *IPGuardian) GinMiddleware() gin.HandlerFunc Gin middleware
IPGuardian.LoginFailure func (i *IPGuardian) LoginFailure(w http.ResponseWriter, r *http.Request) error Increments the current session's login-failure count
IPGuardian.NotFound404 func (i *IPGuardian) NotFound404(w http.ResponseWriter, r *http.Request) error Increments the current session's 404 count

List Management

Accessed through IPGuardian.Manager (type Manager with fields Allow, Block, Deny):

Method Signature Description
AllowIPManager.Add func (m *AllowIPManager) Add(ip string, tag string) error Writes memory, Redis (no expiry), and the list file
AllowIPManager.Check func (m *AllowIPManager) Check(ip string) bool Redis first; memory on a miss or error
DenyIPManager.Add func (m *DenyIPManager) Add(ip, reason string) error Same as Allow, plus an asynchronous email
DenyIPManager.Check func (m *DenyIPManager) Check(ip string) bool Same as Allow
BlockIPManager.Add func (m *BlockIPManager) Add(ip string, reason string) error Temporary block; repeated calls grow the duration
BlockIPManager.IsBlock func (m *BlockIPManager) IsBlock(ip string) bool Whether the IP is blocked; false on a Redis error

AllowIPManager and DenyIPManager export Logger, Config, Redis, Context, Mutex, and Cache (map[string]*IPItem); BlockIPManager exports Logger, Config, Redis, and Context. Hold Mutex before touching Cache directly.

Main Types

type IPGuardian struct {
    Context  context.Context
    Config   *Config
    Redis    *redis.Client
    Logger   *Logger
    GeoLite2 *GeoLite2
    Manager  *Manager
}

type IPGuardianResult struct {
    Success    bool   `json:"success"`
    StatusCode int    `json:"status_code"`
    Error      string `json:"error"`
}

type IPItem struct {
    IP      string `json:"ip"`
    Reason  string `json:"reason"`
    AddedAt int64  `json:"added_at"`
    Count   int    `json:"count,omitempty"`
    Last    int64  `json:"last,omitempty"`
}
Type Description
Config, Redis, Filepath, EmailConfig Settings; see Configuration
Parameter Thresholds and scores; see Parameters
Log Alias of goLogger.Log
Logger Alias of goLogger.Logger; IPGuardian.Logger can be used to write logs
IPItem Format of each list entry in files and Redis; Count / Last are used only by Block

Exported Types for Internal Use

These types are exported but no public function returns or accepts them; they are implementation details and may change between versions:

Type Purpose
Device, IS, IP Device, list status, and IP data parsed by getDevice
ScoreItem One scoring result (IsBlock, IsSuspicious, IsDangerous, Flag, Score, Detail)
RiskScore A dimension's accumulated Base score and Detail
BasicItem Correlation-set settings for calcBasic (all fields unexported)
ScoreTask, ScoreResult Currently unused
GeoLite2 GeoLite2 readers and cache (IPGuardian.GeoLite2, nil when disabled)
GeoLite2Config Currently unused; paths come from Filepath
Location GeoLite2 lookup result (country, city, timezone, coordinates, accuracy radius)
中文