# 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](/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

```go
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](/configuration) |
| `Parameter` | Thresholds and scores; see [Parameters](/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) |